API
Read your project’s data from your own tools.
A read-only JSON API over HTTPS, one project per key, with a scope for each dataset.
Authentication
Scoped keys that expire.
Create a key for one project in Settings → API keys. Owners and editors can manage keys; viewers cannot. Give the key only the scopes it needs and an expiry of 30, 90 or 365 days (90 by default).
The secret is shown once. DiscoveredBy stores only a hash of it, so a lost key is replaced, not recovered. Send it in the Authorization header; session cookies and keys in query parameters
do not authorize these routes, and a key cannot sign in to the app.
curl --fail-with-body \
-H "Authorization: Bearer $DISCOVEREDBY_API_KEY" \
'https://api.discoveredby.ai/customer-api/v1/projects/PROJECT_ID/prompts?limit=50'The 10 scopes:
prompts:readanswers:readcitations:readmetrics:readreports:readreasons:readobjections:readattributes:readfacts:readexplorer:read
Resources
What you can read.
Every path is relative to the project’s base URL, https://api.discoveredby.ai/customer-api/v1/projects/PROJECT_ID. Reports, brand reasons, objections,
attributes and fact checks also need that feature on the project owner’s plan.
| Route | Scope | Returns |
|---|---|---|
| GET /prompts | prompts:read | Current prompts, active and paused, with their classifications |
| GET /answers | answers:read | Completed answers with provenance and a text preview of up to 8,000 characters |
| GET /answers/{answer_id}/text | answers:read | The full saved text of one answer, in version-checked chunks |
| GET /citations | citations:read | Saved citation records with a snippet of up to 2,000 characters |
| GET /metrics/daily | metrics:read | Daily counts, brand visibility and own-domain citation rate by collection channel |
| GET /reports | reports:read | Saved weekly digests for completed weeks |
| GET /reports/{report_id} | reports:read | One saved weekly digest |
| GET /brand-reasons | reasons:read | Strength and weakness reasons answers gave for tracked brands |
| GET /objections | objections:read | Objections found by the objection study |
| GET /attributes | attributes:read | Attributes found by the attribute study, one measure at a time |
| GET /fact-checks | facts:read | Where answers supported or contradicted your approved facts |
| POST /explorer/query | explorer:read | One Explorer query, computed now |
| GET /explorer/views | explorer:read | The project’s saved Explorer views |
| GET /explorer/views/{view_id}/result | explorer:read | One saved view, run now |
Exports
Files in CSV or JSON, from the app.
Separately from the API, the app’s Exports screen downloads thirteen datasets as CSV or JSON, and an Explorer result downloads the same way from the Explorer page. Both formats carry the same rows. File downloads use your signed-in session, not an API key, and follow the project owner’s plan.
Docs: Exports and activityLimits
Rates, pages and windows.
- Each key admits 60 authenticated requests a minute, shared across every route and the MCP connector. On a 429, wait for the Retry-After interval.
- A project can hold up to 10 active keys, and each key reads only its own project.
- Prompt pages hold up to 100 rows; answer, citation, report, reason, objection, attribute and fact check pages up to 25. Follow next_after_id until it is null.
- Daily metrics page by 1–31 calendar days; follow next_start until it is null.
- Dated lists and daily metrics default to the last 28 days and allow a window of at most 366 days.
- Each Explorer query or view result also spends one query from the project’s Explorer budget of 120 a minute, shared with the app.
- Read only. Every route reads data, and there is no refreshable BI connector.
- Missing values stay null; measured zero stays zero.
Plans
Which plans include it.
Access follows the project owner’s plan, whoever created the key. The API and the MCP connector are included together.
| Free | Starter | Growth | Pro |
|---|---|---|---|
Every field, parameter and error.
The API reference covers pagination, field definitions and every status code.