Verte API

GET /usage

Get usage Read

Your plan’s limits and what this billing period has used: clients, prompts, pitches and audit pages.

curl https://api.useverte.com/v1/usage \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients

List clients Read

The client brands your agency tracks, with their ids. Use a client id with the other client endpoints.

Query

curl https://api.useverte.com/v1/clients \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /clients

Create a client Read + write

Adds a client brand to track. Counts against your plan’s clients. Add prompts to it next.

Needs an API key with write access.

JSON body

curl -X POST https://api.useverte.com/v1/clients \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","domain":"…"}'

GET /clients/{client_id}/visibility

Get visibility Read

How often AI answers mention the client: visibility % with "X of Y checks", over a date range, with a point per day or week. Filter by engine.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/visibility \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/share-of-voice

Get share of voice Read

The brand’s share of mentions against its tracked competitors over a date range: brand mentions ÷ (brand + competitor mentions).

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/share-of-voice \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/sentiment

Get sentiment Read

Positive, neutral and negative mentions of the brand over a date range.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/sentiment \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/prompts

List prompts Read

The questions tracked for a client, oldest first, with how often each mentioned the brand in its last 7 daily checks, per engine.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/prompts \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /clients/{client_id}/prompts

Add prompts Read + write

Adds questions to check daily for a client (up to 500 at a time). Each uses one place in your plan’s prompt pool; wording the client already tracks is skipped. Or give generate to have Verte write up to 20: one AI call, needing an active subscription (402) and sharing the org’s 10 AI setup steps a minute (429). A direct call checks first that that many fit in the pool, and a new subcategory named among the client’s 25 (402 before the AI call).

Needs an API key with write access.

Path

JSON body

curl -X POST https://api.useverte.com/v1/clients/{client_id}/prompts \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH /prompts/{prompt_id}

Edit a prompt Read + write

Changes a prompt’s wording, moves it to another of its client’s subcategories (null: “Other prompts”), or deactivates or reactivates it (within the pool). New wording for a Super prompt writes its other wordings again: it needs an active subscription and a plan with Super prompts (402), and takes one of the org’s 50 Super prompt wordings a minute (429).

Needs an API key with write access.

Path

JSON body

curl -X PATCH https://api.useverte.com/v1/prompts/{prompt_id} \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /prompts/{prompt_id}

Deactivate a prompt Read + write

Stops checking a prompt and frees its place in the pool. Its history is kept.

Needs an API key with write access.

Path

curl -X DELETE https://api.useverte.com/v1/prompts/{prompt_id} \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /prompts/deactivate

Deactivate prompts Read + write

Stops checking up to 50 prompts at once, freeing their places in the pool (a Super prompt frees 5). Their history is kept; ones already stopped are left as they are. If any id isn't one of your prompts, nothing changes (404).

Needs an API key with write access.

JSON body

curl -X POST https://api.useverte.com/v1/prompts/deactivate \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt_ids":["…"]}'

POST /prompts/reactivate

Reactivate prompts Read + write

Starts checking up to 50 stopped prompts again, all or none: each needs a place in the pool, a Super prompt 5 and a plan with Super prompts (402), and comes back with its latest wordings. Ones already checked are left as they are; an archived client's prompts are refused (409). If any id isn't one of your prompts, nothing changes (404).

Needs an API key with write access.

JSON body

curl -X POST https://api.useverte.com/v1/prompts/reactivate \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt_ids":["…"]}'

GET /prompts/{prompt_id}/answers

Get prompt answers Read

What the AI engines answered to one prompt, newest first: whether and where the brand was mentioned, sentiment, competitors, other brands named, the answer text (kept 90 days) and the cited sources.

Path

Query

curl https://api.useverte.com/v1/prompts/{prompt_id}/answers \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/subcategories

List subcategories Read

A client’s subcategories (groups of prompts such as “Pricing and value”), in order, with how many prompts each holds. Prompts in none are “Other prompts”.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/subcategories \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /clients/{client_id}/subcategories

Add a subcategory Read + write

Adds a subcategory at the end of a client’s list (up to 25 a client), with the prompts given, or with generate_prompts written by Verte: one AI call, needing an active subscription (402) and sharing the org’s 10 AI setup steps a minute (429). Its prompts use places in the prompt pool, all or none (402); a direct call checks the 25 and the pool before the AI call.

Needs an API key with write access.

Path

JSON body

curl -X POST https://api.useverte.com/v1/clients/{client_id}/subcategories \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

PATCH /subcategories/{subcategory_id}

Rename a subcategory Read + write

Renames or redescribes a subcategory; its prompts and their history stay with it.

Needs an API key with write access.

Path

JSON body

curl -X PATCH https://api.useverte.com/v1/subcategories/{subcategory_id} \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /subcategories/{subcategory_id}

Delete a subcategory Read + write

Removes a subcategory. Its prompts stop being checked (freeing places in the pool) and move to “Other prompts”, keeping their history.

Needs an API key with write access.

Path

curl -X DELETE https://api.useverte.com/v1/subcategories/{subcategory_id} \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/super-prompts

List Super prompts with their findings Read

A client’s Super prompts (each tracked in 5 wordings, rotated through the day) with what the wording and the time of day changed: each wording’s checks, visibility and position per engine; the spread between the best and worst wording (clear when significant with ≥ 20 checks each); visibility in five bands of the local day; the day of week from 28 days. Clearest differences first.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/super-prompts \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /prompts/{prompt_id}/super

Make a prompt a Super prompt Read + write

Tracks a prompt in 5 wordings, rotated through the day (Pro and up). It uses 5 prompt slots instead of 1, so it needs 4 free: a shortage is refused with how many to free (deactivate prompts first). It needs an active subscription (402) and takes one of the org’s 50 Super prompt wordings a minute (429).

Needs an API key with write access.

Path

curl -X POST https://api.useverte.com/v1/prompts/{prompt_id}/super \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /prompts/{prompt_id}/super

Make a Super prompt normal Read + write

It goes back to one wording and 1 prompt slot (4 freed); the other wordings’ history is kept.

Needs an API key with write access.

Path

curl -X DELETE https://api.useverte.com/v1/prompts/{prompt_id}/super \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/competitors

List competitors Read

The competitors tracked for a client, by name.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/competitors \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /clients/{client_id}/competitors

Add a competitor Read + write

Tracks a competitor for a client (up to 25 per client; 402 past them).

Needs an API key with write access.

Path

JSON body

curl -X POST https://api.useverte.com/v1/clients/{client_id}/competitors \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

DELETE /clients/{client_id}/competitors/{competitor_id}

Delete a competitor Read + write

Stops tracking a competitor and deletes its mention history.

Needs an API key with write access.

Path

curl -X DELETE https://api.useverte.com/v1/clients/{client_id}/competitors/{competitor_id} \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/citations

Get citations Read

The sites AI answers cited for a client over a date range, most cited first, with who owns each one. gap=true keeps the citation gaps: third-party sites cited for competitors but not for the brand.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/citations \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /clients/{client_id}/audits

List audits Read

A client’s audits, newest first.

Path

Query

curl https://api.useverte.com/v1/clients/{client_id}/audits \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /clients/{client_id}/audits

Start an audit Read + write

Starts an AI-readiness audit of the client’s website: robots.txt for AI crawlers, llms.txt, and per-page checks. Each page checked uses one audit page of your monthly quota; unchanged pages are free.

Needs an API key with write access.

Path

JSON body

curl -X POST https://api.useverte.com/v1/clients/{client_id}/audits \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /audits/{audit_id}

Get an audit Read

An audit’s status, score, site findings (AI crawlers, llms.txt), issues with fix hints, and pages. Pass audit_id, or client_id for the client’s latest audit.

Path

Query

curl https://api.useverte.com/v1/audits/{audit_id} \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /clients/{client_id}/reports

Create a report Read + write

A white-labelled client report: a share link to its live report over a trailing period (kind link, the default), or a PDF rendered in the background (kind pdf; read its status with GET /report-exports/{id}).

Needs an API key with write access.

Path

JSON body

curl -X POST https://api.useverte.com/v1/clients/{client_id}/reports \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /report-exports/{export_id}

Get a PDF report Read

A PDF report’s status, and its download URL once it is ready.

Path

curl https://api.useverte.com/v1/report-exports/{export_id} \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /report-exports/{export_id}/pdf

Download a PDF report Read

The finished PDF, once GET /report-exports/{export_id} says it is ready.

Path

curl https://api.useverte.com/v1/report-exports/{export_id}/pdf \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /pitch-projects

List pitch projects Read

Your pitch projects, newest first, with the prospect’s visibility so far.

Query

curl https://api.useverte.com/v1/pitch-projects \
  -H "Authorization: Bearer $VERTE_API_KEY"

POST /pitch-projects

Create a pitch project Read + write

Shows a prospect their AI visibility before they sign. Give the prospect's name and website (and, if you like, up to 5 competitors and 2–4 subcategories); Verte researches it and writes 25 prompts a person would ask (they stay hidden), then checks each on every engine in your plan, twice, an hour apart. Uses one pitch of your monthly allowance now; if the pitch can't be prepared it's refunded. Answers 202 with the pitch preparing: read it with GET /pitch-projects/{id}. The project and its share link expire after 30 days.

Needs an API key with write access.

JSON body

curl -X POST https://api.useverte.com/v1/pitch-projects \
  -H "Authorization: Bearer $VERTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prospect_name":"…","domain":"…"}'

GET /pitch-projects/{project_id}

Get a pitch project Read

A pitch project’s report: how often answers mention the prospect and each competitor, per engine and per subcategory, the biggest gaps (with at most 4 example prompts; the 25 prompts stay hidden), site readiness, what to do, and the share link.

Path

curl https://api.useverte.com/v1/pitch-projects/{project_id} \
  -H "Authorization: Bearer $VERTE_API_KEY"

GET /proposals/{proposal_id}

Get a proposal Read

A change proposed through MCP or the Verte Engine: what it does, whether it is waiting, applied, cancelled, expired or failed, who proposed and decided it, and its result once applied.

Path

curl https://api.useverte.com/v1/proposals/{proposal_id} \
  -H "Authorization: Bearer $VERTE_API_KEY"