Developers

Citevant API

Read your results and manage your directory profiles from your own tools, scripts and AI assistants, with a REST API and an MCP server.

Overview

The API gives you the same websites and figures as your dashboard. With it you can list your websites, read and update the directory profile used to list each website on directories, follow your share of voice, editorial backlinks and directory listings, and see every approved directory with its listing link.

Every endpoint lives under https://citevant.com/api/v1, takes and returns JSON, and uses your API key. AI assistants can connect to the same features through the MCP server.

Getting an API key

  1. Open Settings in your dashboard. Agency teams use Settings in the agency dashboard.
  2. Under API keys, give the key a name, such as the tool that will use it, and click Create key.
  3. Copy the key straight away. It is shown only once; if you lose it, revoke it and create another.

Keys start with cv_live_. You can have up to 10 active keys, see when each was last used and revoke any of them at any time; a revoked key stops working immediately.

Authentication

Send your key in the Authorization header of every request:

Authorization: Bearer cv_live_your_key_here

A key acts as you. It reaches exactly the websites you can open in your dashboard: your own websites and, if you are on an agency team, every client website of your agency. Anything your account cannot do, the key cannot do either, and a key stops working if your subscription ends.

Treat keys like passwords: keep them on your server or in your assistant's settings, never in a web page or a public repository.

Rate limits

Each key can make 60 requests per minute. Past that, requests are answered with 429 and a Retry-After header giving the seconds until the next minute starts.

Errors

Every error has the same JSON shape, with a stable code and a readable message:

{
  "error": {
    "code": "invalid_profile",
    "message": "The website URL must be on example.com."
  }
}

Validation errors about one value also carry field, its path in the profile, such as product.keyFeatures[2].

StatusCodeMeaning
401invalid_api_keyThe key is missing, malformed or revoked.
403subscription_requiredThe account behind the key has no active subscription.
403forbiddenThe key can read this website but not change it.
404site_not_foundNo website with this domain, or the key cannot access it.
404profile_not_foundThe website has no directory profile yet.
404not_foundNo such endpoint.
422invalid_jsonThe request body is not valid JSON.
422invalid_profileThe profile breaks a rule; the message says which, and field names the value when it can.
429rate_limitedMore than 60 requests in a minute. Wait for the Retry-After seconds.
500internal_errorSomething went wrong on our side. Try again.

REST reference

List websites

GET/api/v1/sites

The websites your key can access, sorted by domain. agency is set for agency client websites.

Request
curl https://citevant.com/api/v1/sites \
  -H "Authorization: Bearer cv_live_your_key_here"
Response
{
  "sites": [
    {
      "domain": "example.com",
      "name": "Example",
      "websiteUrl": "https://example.com",
      "agency": null
    },
    {
      "domain": "client-site.com",
      "name": "Client Site",
      "websiteUrl": "https://client-site.com",
      "agency": {
        "name": "Your Agency"
      }
    }
  ]
}

Get directory profile

GET/api/v1/sites/{domain}/directory-profile

The website's directory profile: the details directories ask for when listing it. It comes with complete and missing, the required fields still empty. A website without a profile answers 404 profile_not_found.

ParameterInDescription
domainpathThe website's domain, as returned by List websites, e.g. example.com.
Request
curl https://citevant.com/api/v1/sites/example.com/directory-profile \
  -H "Authorization: Bearer cv_live_your_key_here"
Response
{
  "site": {
    "domain": "example.com",
    "name": "Example"
  },
  "profile": {
    "tagline": "Plan, publish and measure your content",
    "slogan": "",
    "tags": "Content marketing, SEO",
    "keywords": [
      "content calendar",
      "seo"
    ],
    "categories": [
      "Marketing"
    ],
    "platform": "Other",
    "package": "v140",
    "isAiPowered": false,
    "productLaunchDate": "",
    "mainScreenshotUrl": "https://example.com/screenshot.png",
    "productSupportEmail": "[email protected]",
    "productSocials": {},
    "product": {
      "name": "Example",
      "url": "https://example.com/",
      "slug": "example",
      "shortDescription": "Example helps small teams plan, publish and measure their content in one place.",
      "longDescription": "Example helps small teams plan, publish and measure their content in one place.",
      "iconUrl": "https://example.com/logo.png"
    },
    "pricing": {
      "pricingModel": "freemium",
      "amount": "19",
      "currency": "USD",
      "billingPeriod": "monthly"
    },
    "author": {
      "name": "Jane Doe",
      "firstName": "Jane",
      "lastName": "Doe",
      "fullName": "Jane Doe",
      "shortName": "Jane Doe",
      "givenName": "Jane",
      "familyName": "Doe",
      "email": "[email protected]",
      "avatarUrl": ""
    },
    "account": {
      "username": "example",
      "usernameAlt": "examplecom",
      "displayName": "Example"
    },
    "location": {
      "country": ""
    },
    "reporting": {
      "reportEmail": "[email protected]"
    }
  },
  "complete": false,
  "missing": [
    "Headline",
    "Slogan",
    "Short tagline",
    "Medium tagline",
    "Extended description",
    "Key features",
    "Target audiences",
    "Use cases",
    "Competitors",
    "Questions and answers",
    "Platforms",
    "Language"
  ],
  "updatedAt": "2026-11-02T09:30:00.000Z"
}

Update directory profile

PUT/api/v1/sites/{domain}/directory-profile

Creates the profile, or replaces it completely, with the same rules as the profile form in your dashboard. Send the whole profile as the request body, in the shape the GET returns: a field you leave out is saved empty. The easiest way is to read the profile, change it and send it back.

The answer is the saved profile with complete, missing and created (true when there was no profile before). A profile that breaks a rule is refused with 422 and nothing is saved; an incomplete one is saved, and missing lists what to add.

ParameterInDescription
domainpathThe website's domain, as returned by List websites, e.g. example.com.
(profile)bodyThe full directory profile as JSON.
Request
curl -X PUT https://citevant.com/api/v1/sites/example.com/directory-profile \
  -H "Authorization: Bearer cv_live_your_key_here" \
  -H "Content-Type: application/json" \
  --data @profile.json
Response
{
  "site": {
    "domain": "example.com",
    "name": "Example"
  },
  "created": false,
  "profile": {
    "tagline": "Plan, publish and measure your content",
    "slogan": "",
    "tags": "Content marketing, SEO",
    "keywords": [
      "content calendar",
      "seo"
    ],
    "categories": [
      "Marketing"
    ],
    "platform": "Other",
    "package": "v140",
    "isAiPowered": false,
    "productLaunchDate": "",
    "mainScreenshotUrl": "https://example.com/screenshot.png",
    "productSupportEmail": "[email protected]",
    "productSocials": {},
    "product": {
      "name": "Example",
      "url": "https://example.com/",
      "slug": "example",
      "shortDescription": "Example helps small teams plan, publish and measure their content in one place.",
      "longDescription": "Example helps small teams plan, publish and measure their content in one place.",
      "iconUrl": "https://example.com/logo.png"
    },
    "pricing": {
      "pricingModel": "freemium",
      "amount": "19",
      "currency": "USD",
      "billingPeriod": "monthly"
    },
    "author": {
      "name": "Jane Doe",
      "firstName": "Jane",
      "lastName": "Doe",
      "fullName": "Jane Doe",
      "shortName": "Jane Doe",
      "givenName": "Jane",
      "familyName": "Doe",
      "email": "[email protected]",
      "avatarUrl": ""
    },
    "account": {
      "username": "example",
      "usernameAlt": "examplecom",
      "displayName": "Example"
    },
    "location": {
      "country": ""
    },
    "reporting": {
      "reportEmail": "[email protected]"
    }
  },
  "complete": false,
  "missing": [
    "Headline",
    "Slogan",
    "Short tagline",
    "Medium tagline",
    "Extended description",
    "Key features",
    "Target audiences",
    "Use cases",
    "Competitors",
    "Questions and answers",
    "Platforms",
    "Language"
  ],
  "updatedAt": "2026-11-16T10:00:00.000Z"
}

Directory profile fields

The profile follows the shape of the example above. product.name and product.urlare needed to save, and the URL must be on the website's own domain. Texts are trimmed, emails and links are checked, the pricing model is free, freemium or paid, the currency a three-letter code such as USD, the billing period monthly or yearly, and dates are YYYY-MM-DD.

A profile is complete, and ready for directory listings, once these are filled in:

  • Product name
  • Website URL
  • Tagline
  • Headline
  • Slogan
  • Short tagline
  • Medium tagline
  • Short description
  • Long description
  • Extended description
  • Logo
  • Screenshot
  • Pricing model
  • Starting price
  • Currency
  • Billing period
  • Tags
  • Keywords
  • Preferred categories
  • Key features
  • Target audiences
  • Use cases
  • Competitors
  • Questions and answers
  • Platforms
  • Language
  • Support email

Some fields are filled in for you on every save and replace whatever you send: the account names, the listing slug, the author's name variants and email (from the support email), the report email and, when there is a company, its founding year and one-line address. Keys the profile does not have are ignored.

Results

GET/api/v1/sites/{domain}/results

Your results in brief. Share of voice is the share of AI answers to your tracked questions that name you, over the last 4 weeks, with the 4 weeks before and the change in percentage points (null when there is nothing to compare), overall and per AI assistant. Editorial backlinks counts the publications that agreed to link to you, in total and over the same weeks. Directory listings counts the directories approved for the website and those it is listed on.

assistant is one of gemini, chatgpt, aioverview, perplexity, claude.

ParameterInDescription
domainpathThe website's domain, as returned by List websites, e.g. example.com.
Request
curl https://citevant.com/api/v1/sites/example.com/results \
  -H "Authorization: Bearer cv_live_your_key_here"
Response
{
  "site": {
    "domain": "example.com",
    "name": "Example"
  },
  "shareOfVoice": {
    "periodWeeks": 4,
    "percent": 32.5,
    "previousPercent": 27.1,
    "change": 5.4,
    "answers": 160,
    "answersNamingYou": 52,
    "byAssistant": [
      {
        "assistant": "chatgpt",
        "answers": 80,
        "answersNamingYou": 30,
        "percent": 37.5
      },
      {
        "assistant": "perplexity",
        "answers": 80,
        "answersNamingYou": 22,
        "percent": 27.5
      }
    ]
  },
  "editorialBacklinks": {
    "won": 14,
    "wonInPeriod": 3,
    "averageDr": 46
  },
  "directoryListings": {
    "approved": 120,
    "listed": 85,
    "waitingForSubmission": 35
  }
}

Directories

GET/api/v1/sites/{domain}/directories

Every directory approved for the website, newest first. status is waiting_for_submission until the website is listed, then listed, with the date and, when available, the link to the listing. Dates are ISO 8601 in UTC.

ParameterInDescription
domainpathThe website's domain, as returned by List websites, e.g. example.com.
Request
curl https://citevant.com/api/v1/sites/example.com/directories \
  -H "Authorization: Bearer cv_live_your_key_here"
Response
{
  "site": {
    "domain": "example.com",
    "name": "Example"
  },
  "approved": 120,
  "listed": 85,
  "waitingForSubmission": 35,
  "directories": [
    {
      "name": "Startup Directory",
      "domain": "startupdirectory.example",
      "dr": 62,
      "status": "listed",
      "approvedAt": "2026-10-20T08:00:00.000Z",
      "listedAt": "2026-10-27T14:12:00.000Z",
      "listingUrl": "https://startupdirectory.example/example"
    },
    {
      "name": "Tools Hub",
      "domain": "toolshub.example",
      "dr": 48,
      "status": "waiting_for_submission",
      "approvedAt": "2026-11-10T08:00:00.000Z",
      "listedAt": null,
      "listingUrl": null
    }
  ]
}

MCP server

Connect an AI assistant that supports the Model Context Protocol, and ask it about your results or have it fill in a directory profile. ChatGPT and Claude connect by signing in with your Citevant account; other assistants use an API key. Either way the server has the same rate limits and access as the REST API.

URLhttps://citevant.com/api/mcp
TransportStreamable HTTP
AuthenticationSign in with Citevant (OAuth), or Authorization: Bearer <your key>

ChatGPT

  1. On chatgpt.com, open Plugins, select + and choose Add custom MCP server.
  2. Name it Citevant and paste the server URL under Connection.
  3. Choose OAuth for authentication, confirm the warning and select Create as a plugin.
  4. Install the plugin, sign in to Citevant and select Allow.
  5. In a chat, type @ and pick Citevant.
Server URL
https://citevant.com/api/mcp

Claude

  1. On claude.ai or in Claude Desktop, open Customize, then Connectors.
  2. Select + Add, then Add custom connector.
  3. Name it Citevant, paste the server URL and select Continue.
  4. Keep the sign-in settings Claude detects and select Add.
  5. Sign in to Citevant and select Allow.
Server URL
https://citevant.com/api/mcp

Claude Code

Run this in your terminal, then check it with /mcp.

claude mcp add --transport http citevant https://citevant.com/api/mcp \
  --header "Authorization: Bearer cv_live_your_key_here"

Codex

Add this to ~/.codex/config.toml and set the key in the shell that starts Codex.

# ~/.codex/config.toml
[mcp_servers.citevant]
url = "https://citevant.com/api/mcp"
bearer_token_env_var = "CITEVANT_API_KEY"

# In your shell
export CITEVANT_API_KEY="cv_live_your_key_here"

Cursor

Add this to ~/.cursor/mcp.json, or .cursor/mcp.json in a project.

{
  "mcpServers": {
    "citevant": {
      "url": "https://citevant.com/api/mcp",
      "headers": {
        "Authorization": "Bearer cv_live_your_key_here"
      }
    }
  }
}

GrokBot

In the desktop app: Connect apps, Add a custom connector, Remote HTTPS. Enter the server URL and add this header.

Server URL:  https://citevant.com/api/mcp
Header:      Authorization: Bearer cv_live_your_key_here

Hermes Agent

Add this to ~/.hermes/config.yaml, then run /reload-mcp or restart Hermes.

mcp_servers:
  citevant:
    url: "https://citevant.com/api/mcp"
    headers:
      Authorization: "Bearer cv_live_your_key_here"

Tools

ToolWhat it does
list_sitesThe websites the key can access.
get_directory_profileA website's directory profile, with what is still missing.
update_directory_profileCreate or replace a website's directory profile.
get_resultsShare of voice, editorial backlinks and directory listings in brief.
list_directoriesApproved directories with their status and listing links.

Every tool except list_sites takes the website's domain; update_directory_profile also takes the full profile. Their answers match the REST endpoints above.

OAuth (sign in)

ChatGPT and Claude, and any MCP client that supports OAuth, connect without a key: you add the server URL, sign in to Citevant and choose Allow on the consent screen. The app then acts as you, with the same websites and access as an API key.

Citevant follows the MCP authorization spec: OAuth 2.1 with PKCE (S256 only), dynamic client registration, Client ID Metadata Documents and resource indicators. A request without a token gets 401 with a WWW-Authenticate header pointing to the discovery documents.

Protected resourcehttps://citevant.com/.well-known/oauth-protected-resource/api/mcp
Authorization serverhttps://citevant.com/.well-known/oauth-authorization-server
Issuerhttps://citevant.com
Authorizehttps://citevant.com/oauth/authorize
Tokenhttps://citevant.com/oauth/token
Registrationhttps://citevant.com/oauth/register
Revocationhttps://citevant.com/oauth/revoke
Resourcehttps://citevant.com/api/mcp
Scopemcp
  • Clients are public: no client secret, PKCE on every sign-in, and redirect URIs that must match exactly. Redirect URIs use https, or http on localhost for apps on your computer.
  • Authorization codes work once, within 60 seconds. Access tokens last 1 hour; refresh tokens last 30 days and are replaced on every use.
  • Access tokens are for the MCP server only. The REST API takes API keys.
  • Every connected app appears under Connected apps in Settings, with when it was connected and last used. Disconnect signs it out straight away; it can also revoke its own tokens through the revocation endpoint.

Questions or something missing? Contact us.