Getting started
Introduction
What you get
The Vidrys API reads the same measurements your dashboard shows: which AI assistants recommend your brand, which questions you lose and to whom, what the answers cite, what to write about it, and whether publishing it changed anything. Everything is JSON over HTTPS, authenticated with an API key.
If you want an AI assistant — Claude, ChatGPT, Cursor, Codex — to read this data and reason about it rather than writing the calls yourself, use the MCP server. It exposes the same endpoints as tools.
Base URL and authentication
Every request goes to https://api.vidrys.com/v1 with a key in the Authorization header. Keys are created by a workspace admin on the Developers page, and the secret is shown once.
curl --request GET \
--url "https://api.vidrys.com/v1/projects" \
--header "Authorization: Bearer $VIDRYS_API_KEY"API and MCP access is included on Grow, Scale and Custom. Reading works on all three; writing needs a read-and-write key, which needs Scale or Custom; bulk exports and webhooks are Custom. Plans & access has the full ladder.
What the API will never return
One rule governs this whole surface: a field leaves only if a dashboard screen shows it. That is what makes it safe to pipe these responses into a third-party AI tool. So the API returns scores, endorsements, citations, briefs and drafts — and never:
- the raw text of an AI answer
- the prompts behind the judge, the brief writer or the draft generator
- ranking, classifier or scoring weight tables
- model names, token counts or costs
- member email addresses or user ids — history says “you”, “a teammate” or “system”
Conventions
| Thing | Convention |
|---|---|
| Ids | UUID strings. A project id from another workspace answers 404, never 403. |
| Scores and rates | Floats from 0 to 100, one decimal. The single exception is a result’s quality, which is 0–1. |
| Deltas | Percentage points or score points, never a ratio. Negative means down. |
| Dates | Days are YYYY-MM-DD; timestamps are ISO 8601 in UTC. |
| Windows | range is 7d, 30d or 90d, counted back from the newest run — not from today. |
| Errors | One envelope: {"error": {"code", "message"}}. |
| Versioning | The path carries the version (/v1). Scores also carry a score_version; never trend across two of them. |
A machine-readable description of this surface is served at https://api.vidrys.com/v1/openapi.json, with a Swagger UI at https://api.vidrys.com/v1/docs.