API v1 Reference (Stub)

Illustrative v1 stub showing example endpoints, authentication, and response shapes consistent with the Outercite data model.

The Outercite API v1 lets you pull citation data, competitor snapshots, and visibility metrics into your own tools. This page is an illustrative stub showing example request and response shapes. It is not a live contract, and the base URL, endpoints, and field names here are examples only. Full endpoint documentation will expand here as the API matures.

The API is v1 and actively evolving. Endpoints, response shapes, and rate limits may change between minor releases. Pin to a specific version where stability matters.

What you'll learn

How authentication works (Bearer token pattern).
The shape of the core resources: citations, competitors, dashboard stats, and keywords.
How field names in API responses align with Outercite's data model.

Base URL

https://api.outercite.com/v1

(Example value. Confirm the live base URL in your workspace settings.) All requests must be made over HTTPS. HTTP requests will be rejected.

Authentication

Outercite uses Bearer token authentication. Pass your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate or revoke API keys from your workspace settings. Agency accounts can generate separate keys per client workspace or a single parent-org key with access to all workspaces.

Keep your API key secret. Do not commit it to version control or expose it in client-side code.

Common request headers

Header	Required	Value
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	For POST/PATCH	`application/json`
`Accept`	Recommended	`application/json`

Platform identifiers

The six tracked AI engines appear in API responses as the following string values:

Platform	Identifier
ChatGPT	`chatgpt`
Claude	`claude`
Perplexity	`perplexity`
Google AI	`google_ai`
Grok	`grok`
DeepSeek	`deepseek`

Endpoints

All endpoints, paths, and response shapes on this page are illustrative examples consistent with the Outercite data model. They are not a guaranteed live contract. Confirm exact paths and field names in your workspace.

List citations

Returns a paginated list of verified citations for the authenticated workspace.

GET /v1/citations

Query parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page, max 100 (default: 25)
`platform`	string	Filter by platform identifier (see table above)
`from`	ISO 8601 date	Start of date range
`to`	ISO 8601 date	End of date range

Example response

Field names follow camelCase to match the Outercite data model.

{
  "data": [
    {
      "id": "cit_01j9xz3p",
      "cited": true,
      "platform": "perplexity",
      "position": 1,
      "sentiment": "positive",
      "confidenceScore": 94,
      "citationType": "positive_recommendation",
      "citationTier": "FEATURED_RECOMMENDATION",
      "effectiveScore": 1.0,
      "proofSnippet": "Brisbane Accounting Group is highly recommended for small business owners seeking local expertise.",
      "competitorsMentioned": ["Rival Co", "Metro Accountants"],
      "checkedAt": "2026-06-07T08:14:22Z",
      "keyword": {
        "id": "prm_7kq2mn",
        "keyword": "best accountant in Brisbane"
      }
    },
    {
      "id": "cit_01j9xz3q",
      "cited": false,
      "platform": "chatgpt",
      "position": null,
      "sentiment": "neutral",
      "confidenceScore": 88,
      "citationType": null,
      "citationTier": null,
      "effectiveScore": 0,
      "proofSnippet": null,
      "competitorsMentioned": ["Rival Co"],
      "checkedAt": "2026-06-07T08:14:55Z",
      "keyword": {
        "id": "prm_7kq2mn",
        "keyword": "best accountant in Brisbane"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 142
  }
}

Citation tier values

Tier	Meaning
`FEATURED_RECOMMENDATION`	Business is the primary or featured answer
`LISTED_ALTERNATIVE`	Business appears in a list of options
`CONTEXTUAL_MENTION`	Business is mentioned in context, not as a recommendation
`PASSING_REFERENCE`	Brief, incidental mention

The effectiveScore (a 0-1 float) weights the citation by tier. FEATURED_RECOMMENDATION carries the most weight; PASSING_REFERENCE the least.

Get a single citation

GET /v1/citations/:id

Returns the full detail for one citation record, including the proof snippet and verification outcome. Fields shown are illustrative; confirm the exact response shape in your workspace.

Example response

{
  "id": "cit_01j9xz3p",
  "cited": true,
  "platform": "perplexity",
  "position": 1,
  "sentiment": "positive",
  "confidenceScore": 94,
  "citationType": "positive_recommendation",
  "citationTier": "FEATURED_RECOMMENDATION",
  "effectiveScore": 1.0,
  "proofSnippet": "Brisbane Accounting Group is highly recommended for small business owners seeking local expertise.",
  "competitorsMentioned": ["Rival Co", "Metro Accountants"],
  "checkedAt": "2026-06-07T08:14:22Z",
  "keyword": {
    "id": "prm_7kq2mn",
    "keyword": "best accountant in Brisbane"
  }
}

The confidence score (0-100) reflects how strongly both verification models agreed on this result. Higher values indicate stronger consensus and a lower chance of a false positive.

List competitors

Returns all competitors tracked in the authenticated workspace.

GET /v1/competitors

Example response

{
  "data": [
    {
      "id": "comp_3xt8b1",
      "name": "Rival Co",
      "website": "https://rivalco.example.com",
      "shareOfVoice": 34,
      "citationCount": 58,
      "avgPosition": 2.1,
      "threatScore": 82,
      "threatLevel": "high",
      "platforms": {
        "chatgpt":    { "citationCount": 12, "avgPosition": 1.8 },
        "claude":     { "citationCount": 9,  "avgPosition": 2.0 },
        "perplexity": { "citationCount": 14, "avgPosition": 1.5 },
        "google_ai":  { "citationCount": 8,  "avgPosition": 3.2 },
        "grok":       { "citationCount": 10, "avgPosition": 2.4 },
        "deepseek":   { "citationCount": 5,  "avgPosition": 2.9 }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 3
  }
}

shareOfVoice is a percentage (0-100). threatScore is 0-100. threatLevel is one of low, moderate, or high.

Get dashboard stats

Returns the aggregate visibility metrics for the authenticated workspace.

GET /v1/dashboard/stats

Example response

{
  "citationRate": 48,
  "visibilityScore": 74,
  "citedThisWeek": 11940,
  "platformCoverageCount": 6,
  "pendingActionsCount": 3,
  "asOf": "2026-06-07T00:00:00Z"
}

citationRate is a percentage (0-100). visibilityScore is a composite score (0-100). platformCoverageCount reflects the number of tracked AI platforms returning at least one citation.

List keywords

Returns all tracked keywords (prompts) for the authenticated workspace.

GET /v1/keywords

Example response

{
  "data": [
    {
      "id": "prm_7kq2mn",
      "keyword": "best accountant in Brisbane",
      "topic": "Local accountant services",
      "visibility": 62,
      "trend": "up",
      "avgPosition": 1.8,
      "platforms": ["chatgpt", "perplexity", "grok", "claude", "deepseek", "google_ai"]
    },
    {
      "id": "prm_9rt4pz",
      "keyword": "small business tax advice Australia",
      "topic": "Tax advisory",
      "visibility": 45,
      "trend": "stable",
      "avgPosition": 2.4,
      "platforms": ["perplexity", "chatgpt", "google_ai"]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 18
  }
}

visibility is a percentage (0-100). trend reflects the direction of change over the current window. platforms lists the identifiers for platforms that returned at least one citation for this keyword.

Error responses

All errors follow a consistent shape:

{
  "error": {
    "code": "unauthorised",
    "message": "Invalid or missing API key."
  }
}

HTTP status	Code	Meaning
401	`unauthorised`	Missing or invalid API key
403	`forbidden`	Key valid but lacks permission for this resource
404	`not_found`	Resource does not exist
422	`validation_error`	Request parameters are invalid
429	`rate_limited`	Too many requests: back off and retry
500	`server_error`	Something went wrong on our end

Rate limits

Rate limits apply per API key. Check the rate-limit headers in each response to see your current allowance and reset time. If you exceed the limit you will receive a 429 response with a Retry-After header indicating how many seconds to wait before retrying.

API v1 Reference (Stub)

What you'll learn

Base URL

Authentication

Common request headers

Platform identifiers

Endpoints

List citations

Get a single citation

List competitors

Get dashboard stats

List keywords

Error responses

Rate limits

Try this in Outercite

Data Definitions

Glossary

How the Pipeline Works

On this page