Browse documentation+

BeVisible API

Read the evidence behind your AI visibility, connect it to internal tools, and automate the work that follows.

Base URLhttps://bevisible.app/api/v1Create API token →

01 / Quickstart

Make your first request

Create an account access token, store it in a server-side environment variable, and use it to list the projects available to your integration.

01
Create a token
Choose only the permissions your integration needs.
02
Store it securely
Save the token as BEVISIBLE_API_KEY. It is shown only once.
03
List projects
Use GET /projects to discover the project IDs you can access.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

200 OK

JSON

{
  "data": {
    "primaryProjectId": "project_2x9m4q",
    "projects": [
      {
        "id": "project_2x9m4q",
        "name": "Acme",
        "url": "https://acme.com",
        "domain": "acme.com",
        "isPrimary": true,
        "scopes": [
          "project:read",
          "visibility:overview"
        ]
      }
    ],
    "count": 1
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Playground

Try the API

Send a real request with your access token and inspect the response without leaving the documentation.

Response

Choose an endpoint and send a request to inspect the live response.

02 / Access

Authentication and scopes

Every API request requires a BeVisible access token in theAuthorizationheader. New tokens start withbv_live_.

In account settings, choose either all projects with one permission set or selected projects with permissions set per project. All-project access also covers projects added later. OAuth tokens remain limited to the projects approved during authorization.

Keep tokens server-side.

Do not put a token in browser code, a public repository, or logs. BeVisible stores only its hash and cannot show it again.

Available scopes

project:read

Read projects and their tracked context.

articles:read

Read generated, scheduled, and published articles.

search:read

Read connected Google Search Console analytics.

visibility:overview

Read visibility overview metrics.

visibility:prompts

Read tracked prompts and prompt tags.

visibility:prompts:write

Add, remove, rename, and delete prompt tags.

visibility:responses

Read AI responses and answer evidence.

visibility:citations

Read citations and citation gaps.

visibility:brands

Read owned and competing brands.

visibility:actions

Read recommended actions and action briefs.

crawlers:read

Read AI crawler analytics and request logs.

03 / Collections

Pagination

Paginated collections return an opaquenextCursor and ahasMore flag. Pass the cursor back unchanged. Do not parse it or construct one yourself.

Request

GET /prompts?limit=20&cursor=bv-v1%3AeyJpZCI6Ii4uLiJ9

04 / Limits

Rate limits

Each token can make 120 requests every 60 seconds. A429 response includes Retry-After. Wait for that many seconds before retrying.

Response headers

RateLimit-Policy: 120;w=60
Retry-After: 17

05 / Failures

Errors and request IDs

Errors useapplication/problem+jsonwith a stable machine-readable code. Log therequestId from every response so support can trace a failed request.

Every endpoint includes the complete response set in its response dropdown. The OpenAPI document defines the same status codes for generated clients.

400invalid_requestInvalid parameters or JSON body

401unauthorizedMissing, invalid, expired, or revoked token

403insufficient_scopeToken lacks the required scope

404endpoint_not_foundAPI endpoint does not exist

404not_foundProject or resource does not exist

405method_not_allowedHTTP method is not supported

429rate_limit_exceededToken exceeded its request limit

500internal_errorUnexpected server error

Response

400 Bad Request

JSON

{
  "type": "https://bevisible.app/docs/api#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The limit parameter is invalid.",
  "instance": "/api/v1/projects/project_2x9m4q/prompts",
  "code": "invalid_request",
  "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6",
  "errors": [
    {
      "path": "limit",
      "message": "The supplied value is not valid for this parameter."
    }
  ]
}

Reference

Endpoints

All request and response bodies use JSON. URL paths use kebab-case; query parameters and JSON fields use camelCase.

Resource

Projects

Discover projects and retrieve their tracked context.

listProjects

List projects

GET/api/v1/projects

List all BeVisible projects available to this connection, including project IDs, domains, scopes, and the primary project.

Required scopeproject:read

Parameters

This endpoint does not accept any parameters.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "primaryProjectId": "project_2x9m4q",
    "projects": [
      {
        "id": "project_2x9m4q",
        "name": "Acme",
        "url": "https://acme.com",
        "domain": "acme.com",
        "isPrimary": true,
        "scopes": [
          "project:read",
          "visibility:overview"
        ]
      }
    ],
    "count": 1
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

getProject

Get project context

GET/api/v1/projects/{projectId}

Return one BeVisible project, tracked brands, visibility platforms, prompt count, latest run, and open action counts.

Required scopeproject:read

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "project": {
      "id": "project_2x9m4q",
      "name": "Acme",
      "domain": "acme.com",
      "blogUrl": "https://acme.com/blog",
      "businessDescription": "AI visibility software for SaaS teams.",
      "targetAudience": "B2B SaaS marketing teams",
      "niche": "AI visibility",
      "language": "en",
      "targetCountryCode": "US",
      "timezone": "America/New_York"
    },
    "visibility": {
      "count": 1,
      "providers": [
        "chatgpt",
        "perplexity",
        "gemini"
      ],
      "promptCount": 48,
      "latestRunAt": "2026-08-28T03:14:22.000Z"
    },
    "brands": [
      {
        "id": "brand_1k9v",
        "name": "Acme",
        "domain": "acme.com",
        "aliases": [
          "Acme AI"
        ],
        "relation": "own",
        "tags": [],
        "logoUrl": "https://acme.com/icon.png",
        "isActive": true,
        "isIgnored": false,
        "createdAt": "2026-08-01T08:00:00.000Z",
        "updatedAt": "2026-08-28T03:14:22.000Z"
      }
    ],
    "actions": {
      "open": 7,
      "highPriorityOpen": 2
    },
    "latestResponseAt": "2026-08-28T03:14:22.000Z"
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Articles

Read generated, scheduled, and published content.

listArticles

List articles

GET/api/v1/projects/{projectId}/articles

List generated, scheduled, published, draft, or failed articles for one project with publication status and timestamps. Use the returned cursor to continue through older articles.

Required scopearticles:read

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

status

string·query

Optional article status filter.

limit

integer·query

Maximum number of articles to return. Defaults to 15.

min 1, max 50

cursor

string·query

Opaque pagination cursor returned by the previous page.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/articles?limit=20&status=published' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "filters": {
      "status": "published"
    },
    "articles": [
      {
        "id": "article_8k2d1p",
        "title": "How to evaluate AI visibility platforms",
        "slug": "evaluate-ai-visibility-platforms",
        "status": "published",
        "wordCount": 1640,
        "scheduledAt": null,
        "generatedAt": "2026-08-20T15:12:00.000Z",
        "publishedAt": "2026-08-21T09:30:00.000Z",
        "createdAt": "2026-08-20T14:58:00.000Z",
        "updatedAt": "2026-08-21T09:30:00.000Z",
        "error": null
      }
    ],
    "count": 1,
    "hasMore": true,
    "nextCursor": "bv-v1:eyJpZCI6Ii4uLiJ9"
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

getArticle

Get article

GET/api/v1/projects/{projectId}/articles/{articleId}

Return one article from one project with its full content, metadata, publication status, and timestamps.

Required scopearticles:read

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

articleIdrequired

string·path

Article document id returned by list_articles.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/articles/article_8k2d1p' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "article": {
      "id": "article_8k2d1p",
      "title": "How to evaluate AI visibility platforms",
      "slug": "evaluate-ai-visibility-platforms",
      "status": "published",
      "wordCount": 1640,
      "scheduledAt": null,
      "generatedAt": "2026-08-20T15:12:00.000Z",
      "createdAt": "2026-08-20T14:58:00.000Z",
      "updatedAt": "2026-08-21T09:30:00.000Z",
      "error": null,
      "metaTitle": "How to evaluate AI visibility platforms",
      "metaDescription": "A practical framework for comparing AI visibility platforms.",
      "content": "# How to evaluate AI visibility platforms\n\n...",
      "contentFormat": "markdown",
      "featuredImageUrl": "https://assets.bevisible.app/featured-images/evaluate-ai-visibility-platforms.png",
      "featuredImageAlt": "AI visibility platform evaluation dashboard",
      "publishedAt": "2026-08-21T09:30:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Search analytics

Access connected Google Search Console performance.

getSearchAnalytics

Get search analytics

GET/api/v1/projects/{projectId}/search-analytics

Return Google Search Console totals, comparison totals, traffic trend, leading queries, and leading pages for one project.

Required scopesearch:read

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

range

7d | 28d | 90d | 180d·query

Google Search Console time range. Defaults to 28d.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/search-analytics?range=7d' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "available": true,
    "range": "7d",
    "totals": {
      "clicks": 1842,
      "impressions": 68410,
      "avgCtr": 0.0269,
      "avgPosition": 12.4
    },
    "comparisonTotals": {
      "clicks": 1607,
      "impressions": 62118,
      "avgCtr": 0.0259,
      "avgPosition": 13.1
    },
    "topQueries": [
      {
        "query": "ai visibility tools",
        "clicks": 94,
        "impressions": 2310
      }
    ],
    "topPages": [
      {
        "page": "https://acme.com/ai-visibility",
        "clicks": 181,
        "impressions": 4420
      }
    ]
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Visibility

Read high-level AI visibility and citation metrics.

getVisibilityOverview

Get visibility overview

GET/api/v1/projects/{projectId}/visibility

Return brand visibility, responses, citations, citation share, top cited domains, and recent actions for one project. Defaults to the same organic visibility scope used in BeVisible.

Required scopevisibility:overview

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

range

24h | 7d | 30d | 90d | all·query

Time range for visibility analytics. Defaults to 7d.

from

string·query

Optional ISO start date.

to

string·query

Optional ISO end date.

provider

string·query

Optional AI platform filter: chatgpt, gemini, perplexity, ai-mode, or ai-overviews.

metricScope

organic | all·query

organic excludes branded alternative/comparison/review prompts; all includes every prompt.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/visibility?range=30d&provider=chatgpt' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "filters": {
      "range": "30d",
      "provider": null,
      "metricScope": "organic"
    },
    "metrics": {
      "visibility": 62.5,
      "responses": 240,
      "citations": 318,
      "citationShare": 21.7
    },
    "sampledResponses": 240,
    "includedPromptCount": 48,
    "topDomains": [
      {
        "domain": "acme.com",
        "citations": 69,
        "examples": []
      }
    ]
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Crawlers

Inspect verified AI crawler traffic and request logs.

getCrawlerAnalytics

Get AI Crawler Analytics

GET/api/v1/projects/{projectId}/crawler-analytics

Return AI crawler visits, categories, providers, top pages, missing pages, and recent activity for one project.

Required scopecrawlers:read

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

range

24h | 7d | 30d | 90d | all·query

Time range for visibility analytics. Defaults to 7d.

from

string·query

Optional ISO start date.

to

string·query

Optional ISO end date.

provider

string·query

Optional crawler provider key from a previous overview.

category

answer_fetch | indexing | training | other_ai·query

Optional AI crawler category filter.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/crawler-analytics?range=30d&provider=chatgpt' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "project": {
      "id": "project_2x9m4q",
      "name": "Acme",
      "domain": "acme.com"
    },
    "filters": {
      "range": "30d",
      "provider": null,
      "category": null
    },
    "metrics": {
      "visits": 1248,
      "providers": 8,
      "pages": 96,
      "missingPages": 3
    },
    "providers": [
      {
        "key": "openai",
        "name": "OpenAI",
        "visits": 412
      }
    ],
    "topPages": [
      {
        "path": "/pricing",
        "visits": 118,
        "missingVisits": 0
      }
    ]
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

listCrawlerLogs

List AI Crawler Logs

GET/api/v1/projects/{projectId}/crawler-logs

List recent AI crawler requests for one project, including bot, provider, category, requested path, HTTP status, and verification state.

Required scopecrawlers:read

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

range

24h | 7d | 30d | 90d | all·query

Time range for visibility analytics. Defaults to 7d.

from

string·query

Optional ISO start date.

to

string·query

Optional ISO end date.

provider

string·query

Optional crawler provider key.

category

answer_fetch | indexing | training | other_ai·query

Optional AI crawler category filter.

path

string·query

Optional exact request path, for example /pricing.

statusCode

integer·query

Optional HTTP status code filter.

min 100, max 599

limit

integer·query

Maximum number of rows to return.

min 1, max 100

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/crawler-logs?range=30d&limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "filters": {
      "range": "30d",
      "provider": null,
      "statusCode": null
    },
    "events": [
      {
        "id": "crawler_event_3d8k",
        "provider": "openai",
        "category": "answer_fetch",
        "path": "/pricing",
        "statusCode": 200,
        "verificationStatus": "verified",
        "timestamp": "2026-08-28T06:24:10.000Z"
      }
    ],
    "count": 1,
    "hasMore": false
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Prompts

Read tracked prompts and maintain their taxonomy.

listPromptTags

List prompt tags

GET/api/v1/projects/{projectId}/prompt-tags

List the complete prompt-tag catalog for one project with total and active prompt counts. Supports search and pagination.

Required scopevisibility:prompts

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

search

string·query

Optional case-insensitive tag-name search.

limit

integer·query

Maximum number of rows to return.

min 1, max 100

cursor

string·query

Opaque pagination cursor returned by the previous page.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/prompt-tags?limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "filters": {
      "search": null
    },
    "tags": [
      {
        "name": "comparison",
        "promptCount": 12,
        "activePromptCount": 10
      }
    ],
    "count": 1,
    "totalCount": 6,
    "hasMore": false,
    "nextCursor": null,
    "totalPrompts": 48,
    "activePrompts": 44,
    "untaggedPrompts": 3,
    "activeUntaggedPrompts": 2
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

renamePromptTag

Rename a prompt tag

PATCH/api/v1/projects/{projectId}/prompt-tags/{tag}

Rename or delete a tag everywhere in one project. Renaming merges duplicates when the replacement already exists. Requires prompt-tag write access.

Required scopevisibility:prompts:write

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

tagrequired

string·path

Existing tag to manage.

newTagrequired

string·body

Required replacement tag when operation is rename.

Request

curl --request PATCH \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/prompt-tags/commercial' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "newTag": "buyer-intent"
}'

Response

JSON

{
  "data": {
    "operation": "rename",
    "tag": "commercial",
    "newTag": "buyer-intent",
    "matched": 8,
    "updated": 8,
    "totalPrompts": 48
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

deletePromptTag

Delete a prompt tag

DELETE/api/v1/projects/{projectId}/prompt-tags/{tag}

Rename or delete a tag everywhere in one project. Renaming merges duplicates when the replacement already exists. Requires prompt-tag write access.

Required scopevisibility:prompts:write

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

tagrequired

string·path

Existing tag to manage.

Request

curl --request DELETE \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/prompt-tags/commercial' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "operation": "delete",
    "tag": "commercial",
    "newTag": null,
    "matched": 8,
    "updated": 8,
    "totalPrompts": 48
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

listPrompts

List prompts

GET/api/v1/projects/{projectId}/prompts

List tracked prompts for one project with taxonomy, AI platform, public 1-5 Prompt Volume score, status, run count, and latest run timestamps.

Required scopevisibility:prompts

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

limit

integer·query

Maximum number of rows to return.

min 1, max 100

provider

string·query

Optional AI platform filter, for example ai-mode.

activeOnly

boolean·query

Set false to include inactive prompts.

tags

string[]·query

Optional prompt tags to match.

tagMatch

any | all·query

Match any selected tag or require all. Defaults to any.

untaggedOnly

boolean·query

Return only prompts without tags.

cursor

string·query

Opaque pagination cursor returned by the previous page.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/prompts?limit=20&provider=chatgpt' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "filters": {
      "provider": "chatgpt",
      "activeOnly": true,
      "tags": [],
      "tagMatch": "any"
    },
    "prompts": [
      {
        "id": "prompt_6h4s9v",
        "monitorId": "monitor_2j7q",
        "prompt": "What are the best AI visibility tools for SaaS teams?",
        "provider": "chatgpt",
        "status": "active",
        "type": "comparison",
        "questionFrame": "comparison",
        "brandScope": "category",
        "intent": "commercial",
        "tags": [
          "comparison"
        ],
        "isActive": true,
        "volumeScore": 4,
        "volumeStatus": "estimated",
        "difficulty": 42,
        "runCount": 10,
        "lastRunAt": "2026-08-28T03:14:22.000Z",
        "nextRunAt": "2026-08-29T03:14:22.000Z",
        "createdAt": "2026-08-01T08:00:00.000Z",
        "updatedAt": "2026-08-28T03:14:22.000Z"
      }
    ],
    "count": 1,
    "totalCount": 48,
    "hasMore": true,
    "nextCursor": "bv-v1:eyJpZCI6Ii4uLiJ9"
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

updatePromptTags

Update tags on prompts

PATCH/api/v1/projects/{projectId}/prompts/tags

Add, remove, or replace all tags on one or many tracked prompts. Supports up to 500 prompts per call and requires prompt-tag write access.

Required scopevisibility:prompts:write

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

promptIdsrequired

string[]·body

One to 500 tracked prompt document ids.

operationrequired

add | remove | set·body

How to apply the supplied tags to every prompt.

tagsrequired

string[]·body

Up to 12 prompt tags.

Request

curl --request PATCH \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/prompts/tags' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "promptIds": [
    "prompt_6h4s9v",
    "prompt_3n8c2w"
  ],
  "operation": "add",
  "tags": [
    "comparison",
    "buyer-intent"
  ]
}'

Response

JSON

{
  "data": {
    "operation": "add",
    "requested": 2,
    "updated": 2,
    "unchanged": 0,
    "prompts": [
      {
        "promptId": "prompt_6h4s9v",
        "tags": [
          "comparison",
          "buyer-intent"
        ],
        "changed": true
      }
    ]
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

getPrompt

Get prompt

GET/api/v1/projects/{projectId}/prompts/{promptId}

Return a tracked prompt from one project with recent responses, mentioned brands, citations, and prompt-level metrics.

Required scopevisibility:prompts

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

promptIdrequired

string·path

Tracked prompt document id.

range

24h | 7d | 30d | 90d | all·query

Time range for visibility analytics. Defaults to 7d.

provider

string·query

Optional AI platform filter, for example ai-overviews.

limit

integer·query

Maximum number of rows to return.

min 1, max 100

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/prompts/prompt_6h4s9v?range=30d&limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "prompt": {
      "id": "prompt_6h4s9v",
      "prompt": "What are the best AI visibility tools for SaaS teams?",
      "provider": "chatgpt",
      "tags": [
        "comparison"
      ]
    },
    "metrics": {
      "responses": 10,
      "visibility": 70,
      "citations": 18
    },
    "responses": [
      {
        "id": "response_7f3m2k",
        "ownBrandMentioned": true,
        "visibilityScore": 82
      }
    ]
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Responses

Retrieve AI answers, mentions, sentiment, and evidence.

listResponses

List responses

GET/api/v1/projects/{projectId}/responses

List recent AI responses for one project with prompt text, brand mentions, citations, sentiment, and visibility scores.

Required scopevisibility:responses

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

range

24h | 7d | 30d | 90d | all·query

Time range for visibility analytics. Defaults to 7d.

from

string·query

Optional ISO start date.

to

string·query

Optional ISO end date.

provider

string·query

Optional AI platform filter, for example chatgpt.

promptId

string·query

Optional tracked prompt id filter.

limit

integer·query

Maximum number of rows to return.

min 1, max 100

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/responses?range=30d&limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "responses": [
      {
        "id": "response_7f3m2k",
        "runId": "run_2m8j",
        "promptId": "prompt_6h4s9v",
        "prompt": "What are the best AI visibility tools for SaaS teams?",
        "provider": "chatgpt",
        "model": "gpt-5",
        "answer": "Several platforms help SaaS teams track their presence...",
        "ownBrandMentioned": true,
        "ownBrandPosition": 2,
        "visibilityScore": 82,
        "sentimentScore": 0.74,
        "mentionedBrands": [],
        "citationCount": 1,
        "citations": [
          {
            "id": "citation_5w2n",
            "url": "https://acme.com/ai-visibility",
            "domain": "acme.com",
            "title": "AI visibility for SaaS teams",
            "snippet": "Track how AI systems describe and cite your brand.",
            "position": 1,
            "sourceName": "Acme",
            "createdAt": "2026-08-28T03:14:22.000Z"
          }
        ],
        "receivedAt": "2026-08-28T03:14:22.000Z",
        "createdAt": "2026-08-28T03:14:20.000Z"
      }
    ],
    "count": 1
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

getResponse

Get response

GET/api/v1/projects/{projectId}/responses/{responseId}

Return one AI response from one project with full citations, mentioned brands, prompt, and run status.

Required scopevisibility:responses

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

responseIdrequired

string·path

visibility_responses document id.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/responses/response_7f3m2k' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "response": {
      "id": "response_7f3m2k",
      "provider": "chatgpt",
      "prompt": "What are the best AI visibility tools for SaaS teams?",
      "answer": "Several platforms help SaaS teams track their presence...",
      "ownBrandMentioned": true,
      "citations": [
        {
          "domain": "acme.com",
          "url": "https://acme.com/ai-visibility"
        }
      ]
    },
    "run": {
      "id": "run_2m8j",
      "provider": "chatgpt",
      "status": "completed"
    }
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Citations

Inspect cited sources and discover citation gaps.

listCitations

List citations

GET/api/v1/projects/{projectId}/citations

List cited URLs and domains from one project's AI responses, filterable by domain, prompt, or response.

Required scopevisibility:citations

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

domain

string·query

Optional cited domain filter.

promptId

string·query

Optional tracked prompt id filter.

responseId

string·query

Optional response id filter.

limit

integer·query

Maximum number of rows to return.

min 1, max 100

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/citations?limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "citations": [
      {
        "id": "citation_5w2n",
        "domain": "acme.com",
        "url": "https://acme.com/ai-visibility",
        "title": "AI visibility for SaaS teams",
        "snippet": "Track how AI systems describe and cite your brand.",
        "position": 1,
        "sourceName": "Acme",
        "createdAt": "2026-08-28T03:14:22.000Z"
      }
    ],
    "count": 1
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

getCitationGaps

Get citation gaps

GET/api/v1/projects/{projectId}/citation-gaps

Find recent responses for one project where the brand is missing, competitors are mentioned, or the brand appears without the owned domain being cited.

Required scopevisibility:citations

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

range

24h | 7d | 30d | 90d | all·query

Time range for visibility analytics. Defaults to 7d.

provider

string·query

Optional AI platform filter, for example perplexity.

limit

integer·query

Maximum number of rows to return.

min 1, max 100

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/citation-gaps?range=30d&limit=20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "project": {
      "id": "project_2x9m4q",
      "name": "Acme",
      "domain": "acme.com"
    },
    "gaps": [
      {
        "type": "own_domain_missing",
        "responseId": "response_7f3m2k",
        "promptId": "prompt_6h4s9v",
        "reason": "Acme was mentioned, but acme.com was not cited.",
        "citedDomains": [
          "example.com"
        ]
      }
    ],
    "count": 1
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Brands

Read the owned brand and tracked competitors.

listBrands

List brands

GET/api/v1/projects/{projectId}/brands

List the owned brand and competitors BeVisible tracks for one project.

Required scopevisibility:brands

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

relation

string·query

Optional relation filter such as own or direct_competitor.

includeIgnored

boolean·query

Include ignored brands.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/brands' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "brands": [
      {
        "id": "brand_1k9v",
        "name": "Acme",
        "domain": "acme.com",
        "aliases": [
          "Acme AI"
        ],
        "relation": "own",
        "tags": [],
        "logoUrl": "https://acme.com/icon.png",
        "isActive": true,
        "isIgnored": false,
        "createdAt": "2026-08-01T08:00:00.000Z",
        "updatedAt": "2026-08-28T03:14:22.000Z"
      },
      {
        "id": "brand_8c4q",
        "name": "Example",
        "domain": "example.com",
        "aliases": [],
        "relation": "direct_competitor",
        "tags": [
          "enterprise"
        ],
        "logoUrl": null,
        "isActive": true,
        "isIgnored": false,
        "createdAt": "2026-08-02T08:00:00.000Z",
        "updatedAt": "2026-08-27T03:14:22.000Z"
      }
    ],
    "count": 2
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Resource

Actions

Turn visibility evidence into prioritized work.

listActions

List actions

GET/api/v1/projects/{projectId}/actions

List BeVisible actions generated from one project's visibility evidence.

Required scopevisibility:actions

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

status

string·query

Optional action status filter.

priority

string·query

Optional priority filter.

type

string·query

Optional action type filter.

limit

integer·query

Maximum number of rows to return.

min 1, max 100

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/actions?limit=20&status=open' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "actions": [
      {
        "id": "action_4p9v6j",
        "title": "Earn citations for the AI visibility guide",
        "type": "content_update",
        "priority": "high",
        "status": "open",
        "description": "Add first-party evidence and earn relevant citations.",
        "targetUrl": "https://acme.com/ai-visibility",
        "articleId": "article_8k2d1p",
        "evidenceResponseIds": [
          "response_7f3m2k"
        ],
        "evidenceCitationIds": [
          "citation_5w2n"
        ],
        "targetPromptIds": [
          "prompt_6h4s9v"
        ],
        "createdAt": "2026-08-28T03:30:00.000Z",
        "updatedAt": "2026-08-28T03:30:00.000Z"
      }
    ],
    "count": 1
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

getActionBrief

Get action brief

GET/api/v1/projects/{projectId}/actions/{actionId}/brief

Create an agent-ready brief for one project's visibility action, including project context, objective, and source evidence.

Required scopevisibility:actions

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

actionIdrequired

string·path

Visibility action document id.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/actions/action_4p9v6j/brief' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "project": {
      "id": "project_2x9m4q",
      "name": "Acme",
      "domain": "acme.com"
    },
    "objective": "Earn citations for the AI visibility guide",
    "instructions": [
      "Use the included prompts, responses, and citation evidence as the source of truth.",
      "Do not claim live publishing access through the API."
    ],
    "action": {
      "id": "action_4p9v6j",
      "priority": "high",
      "status": "open"
    }
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

getAction

Get action

GET/api/v1/projects/{projectId}/actions/{actionId}

Return one visibility action from one project with evidence prompts, responses, citations, and linked article status.

Required scopevisibility:actions

Parameters

ParameterDescription

projectIdrequired

string·path

Authorized project ID or domain.

actionIdrequired

string·path

Visibility action document id.

Request

curl --request GET \
  --url 'https://bevisible.app/api/v1/projects/project_2x9m4q/actions/action_4p9v6j' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $BEVISIBLE_API_KEY'

Response

JSON

{
  "data": {
    "action": {
      "id": "action_4p9v6j",
      "title": "Earn citations for the AI visibility guide",
      "type": "content_update",
      "priority": "high",
      "status": "open",
      "description": "Add first-party evidence and earn relevant citations.",
      "targetUrl": "https://acme.com/ai-visibility",
      "articleId": "article_8k2d1p",
      "targetPromptIds": [
        "prompt_6h4s9v"
      ],
      "evidenceResponseIds": [
        "response_7f3m2k"
      ],
      "evidenceCitationIds": [
        "citation_5w2n"
      ],
      "createdAt": "2026-08-28T03:30:00.000Z",
      "updatedAt": "2026-08-28T03:30:00.000Z",
      "article": {
        "id": "article_8k2d1p",
        "title": "How to evaluate AI visibility platforms",
        "slug": "evaluate-ai-visibility-platforms",
        "status": "published",
        "scheduledAt": null,
        "publishedAt": "2026-08-21T09:30:00.000Z"
      },
      "prompts": [],
      "responses": [],
      "citations": []
    }
  },
  "meta": {
    "requestId": "req_01J6F2Q8M7S4V3K9W1X5Y0Z2A6"
  }
}

Need help with an integration? Contact team@bevisible.app.

BeVisible API

Make your first request

Create a token

Store it securely

List projects

Try the API

Authentication and scopes

Pagination

Rate limits

Errors and request IDs

Endpoints

Projects

List projects

Parameters

Get project context

Parameters

Articles

List articles

Parameters

Get article

Parameters

Search analytics

Get search analytics

Parameters

Visibility

Get visibility overview

Parameters

Crawlers

Get AI Crawler Analytics

Parameters

List AI Crawler Logs

Parameters

Prompts

List prompt tags

Parameters

Rename a prompt tag

Parameters

Delete a prompt tag

Parameters

List prompts

Parameters

Update tags on prompts

Parameters

Get prompt

Parameters

Responses

List responses

Parameters

Get response

Parameters

Citations

List citations

Parameters

Get citation gaps

Parameters

Brands

List brands

Parameters

Actions

List actions

Parameters

Get action brief

Parameters

Get action

Parameters