API access

The public API v1 gives you your own data for your own dashboards, scripts and warehouse. Keys are scoped, rate-limited per plan, and read-only by default.

What you'll learn

• How to create a key and what scopes it gets
• How to authenticate, and what the responses look like
• What you can read and write

Create a key

1. Open API settings.
2. Create a key and copy it immediately. It is shown once.
3. Restrict its permissions to what the integration needs.

A new key defaults to read-only permissions. Write and trigger permissions are opt-in, deliberately.

Authenticate

Send the key as a bearer token:

curl -H "Authorization: Bearer $OUTERCITE_API_KEY" \
  https://app.outercite.com/api/v1/citations

A missing or malformed header returns 401 with a message telling you the expected form. Rate limits come from your plan and are reported back on the response headers, so a client can back off rather than guess.

Permissions

What you can reach

Endpoints exist for citations, prompts and their trends, competitors and the competitive landscape, insights, actions, changes, forecasts, platform coverage, briefs, products, Trace visits, webhooks and dashboard stats. Agencies can scope a request to a client workspace where the key carries the cross-workspace permission.

Two conventions worth knowing before you write a client:

• Lists are paginated, with the total returned alongside the rows.
• Unknown values are rejected rather than ignored. Asking for an unrecognised platform id returns a validation error listing the valid ids, instead of quietly creating a prompt that gets checked on nothing.

Naming note

Some endpoints and permissions still say keywords where the product says prompts. They are the same thing: the path is kept stable so existing integrations keep working.

Rate limits and etiquette

Your limit comes from your plan. Three habits that keep you inside it:

1. Poll on a schedule that matches the check cadence, not every minute. Checks do not run continuously.
2. Use webhooks for anything event-shaped. Polling for a citation loss is wasteful and slower.
3. Cache reference data such as your prompt list.

Try this in Outercite

Create a read-only key and pull GET /api/v1/platforms/coverage. It is the smallest useful request and it confirms your authentication, your plan's surfaces and your rate-limit headers in one call.

Related