{ "openapi": "3.1.0", "info": { "title": "Epovest API", "version": "1.0.0", "summary": "Measure how AI assistants answer the questions your market asks, and shape those answers.", "description": "Epovest is an AI visibility platform: it measures how AI assistants such as ChatGPT, Claude,\nGemini, Perplexity, Mistral and Grok answer the questions a market asks (which names they cite,\nwith which sources, how that changes over time), and gives businesses the levers to shape those\nanswers and get recommended.\n\nEvery call carries an API key in the `Authorization` header: `Authorization: Bearer epo_...`.\nKeys belong to an Epovest account and are created by its owner in the app. Scopes are chosen at\ncreation: `read`, which every key has, and `write`, for creating and changing things. Each\noperation of this document states the scope it takes under `x-scope`.\n\nThe same surface is served as MCP tools at `https://mcp.epovest.com/mcp`, one tool per route:\neach operation names its tool under `x-mcp-tool`. The prose reference of both surfaces is at\nhttps://epovest.com/docs/api.md, and the task recipes at https://epovest.com/docs/recipes.md.\n\nThe canonical base URL is `https://api.epovest.com/v1`. The base delivered earlier,\n`https://app.epovest.com/api/v1`, answers identically.\n\nRate limit: 120 requests per minute per credential, sliding window. Beyond the budget the API\nanswers `429 rate_limited` with a `Retry-After` header and the `X-RateLimit-Limit` and\n`X-RateLimit-Remaining` counters. MCP calls draw from the same budget.\n\nConventions: dates are ISO 8601 with timezone, survey periods are plain `YYYY-MM-DD` dates,\nenumerations use their lowercase value, monetary amounts are integers in minor units suffixed\n`_minor` next to a `currency` field, errors always use the envelope\n`{\"error\": \"slug\", \"message\": \"human sentence\"}`, and paginated routes answer with `pagination`\nas `{page, per_page, total, pages}` where `page` is clamped rather than rejected: ask for page 99\nof 3 and you get page 3 back, so stop on `pagination.page >= pagination.pages`.\n", "contact": { "name": "Epovest", "url": "https://epovest.com/docs/api.md" }, "x-brand-owner": "Epovest is a brand operated by Sels de Rehy, LLC, a limited liability company incorporated in the State of Delaware, United States.", "x-providerName": "epovest.com", "x-apisguru-categories": [ "marketing", "analytics" ], "x-logo": { "url": "https://epovest.com/icon.svg" }, "x-tags": [ "AI visibility", "Generative engine optimization", "Brand monitoring", "ChatGPT", "Claude", "Gemini", "Perplexity", "MCP" ] }, "externalDocs": { "description": "The prose reference of the REST and MCP surfaces, and the task recipes.", "url": "https://epovest.com/docs/api.md" }, "servers": [ { "url": "https://api.epovest.com/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Trackers", "description": "The trackers of the account: what is asked, to which engines, at which pace." }, { "name": "Results", "description": "The surveys of a tracker chain, the score series and the raw engine answers." }, { "name": "Keyword discovery", "description": "The domains that keep coming back in the surveyed engines' sources while no tracked keyword covers them." }, { "name": "Projects", "description": "The folders trackers are filed under, and the brand canon each one carries." }, { "name": "Surfaces", "description": "The pages about the brand where the customer has the final say, and their alignment with the canon." }, { "name": "Corroborations", "description": "The pages about the brand where someone else has the final say, and what a reading of each one reports." }, { "name": "Logbook", "description": "The dated moves of the GEO work, readable against the citation curves." }, { "name": "Quests", "description": "What there is to do for the GEO work, and what the measurement holds for review." }, { "name": "Competitor scans", "description": "A basket of up to 5 companies of one market, and the places that corroborate them." }, { "name": "Atlas", "description": "The map of the sources the AIs cite when they answer your trackers." }, { "name": "Account", "description": "The settings of the account: billing identity, language and time zone." }, { "name": "Credits", "description": "The prepaid balance, what it is worth in months, and the hosted top-up page." }, { "name": "Usage", "description": "What the account has spent, by month, by cost line, by project and by tracker." }, { "name": "Support", "description": "The humans behind Epovest, and the threads they answer in." } ], "paths": { "/trackers": { "get": { "operationId": "listTrackers", "summary": "List the trackers of the account", "description": "The trackers of the account, current versions, the ones still followed first and then the\nones filed away.\n", "tags": [ "Trackers" ], "x-scope": "read", "x-mcp-tool": "list_trackers", "parameters": [ { "name": "project", "in": "query", "required": false, "description": "A project UUID, or `default` for the trackers filed under no project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The trackers of the account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "trackers" ], "properties": { "trackers": { "type": "array", "items": { "$ref": "#/components/schemas/Tracker" } } } } } } }, "404": { "description": "The `project` filter names no project of the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createTracker", "summary": "Create a tracker, in draft", "description": "Creates a tracker in draft: it measures nothing until started. Starting it launches its first\nsurvey immediately, unless it carries a chosen `next_survey_at` still in the future, in which\ncase the grid starts on that date. Manager or above.\n", "tags": [ "Trackers" ], "x-scope": "write", "x-mcp-tool": "create_tracker", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackerCreate" } } } }, "responses": { "201": { "description": "The tracker, in draft.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tracker" ], "properties": { "tracker": { "$ref": "#/components/schemas/Tracker" } } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "get": { "operationId": "getTracker", "summary": "Read one tracker", "description": "One tracker, by id. A retired version still answers here with `status: \"retired\"`, so after an\nedit that made a new version, follow the new id rather than the one you had cached.\n", "tags": [ "Trackers" ], "x-scope": "read", "responses": { "200": { "description": "The tracker.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tracker" ], "properties": { "tracker": { "$ref": "#/components/schemas/Tracker" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateTracker", "summary": "Update the configuration of a tracker", "description": "Takes the same fields as the creation, all optional: only the fields you send change, and a\nsent list replaces the previous one entirely. Keywords, analysts and the title apply in\nplace. Changing the prompts, engines, frequency or resolution of a tracker that has measured\ncreates a new version: the score series continues across versions, and the response carries\nthe new tracker with its new id, next to `version_created`. Manager or above.\n", "tags": [ "Trackers" ], "x-scope": "write", "x-mcp-tool": "update_tracker", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackerUpdate" } } } }, "responses": { "200": { "description": "The tracker as it now stands, and whether a version was created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tracker", "version_created" ], "properties": { "tracker": { "$ref": "#/components/schemas/Tracker" }, "version_created": { "type": "boolean", "description": "True when the edit recorded a new tracker version, which carries a new id." } } } } } }, "409": { "description": "`not_editable`: a retired version is revision history, or a paused tracker was asked for\nan edit that would create a version. The message says which one it is.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/start": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "post": { "operationId": "startTracker", "summary": "Start or restart the measurement", "description": "Starts the measurement against the credit balance. Replaying it on a tracker already\nmeasuring answers with that tracker. Owner only.\n", "tags": [ "Trackers" ], "x-scope": "write", "x-mcp-tool": "start_tracker", "responses": { "200": { "description": "The tracker, measuring.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tracker" ], "properties": { "tracker": { "$ref": "#/components/schemas/Tracker" } } } } } }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "409": { "description": "`tracker_archived`: bring it back first with `POST /trackers/{id}/archive` and\n`{\"archived\": false}`. `not_startable`: a retired version never restarts, work on the\ncurrent version instead.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/survey": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "post": { "operationId": "surveyNow", "summary": "Run one survey now, on top of the schedule", "description": "Runs one survey NOW: the anchor, the frequency and the date of the next scheduled survey are\nuntouched. Answers `201` with the survey, which carries `on_demand: true` and `requested_at`;\nits point joins the series under the same period, told apart by `on_demand`. Debits the\nbalance like any survey. While one is still running, answers `200` with THAT survey.\nA refusal never pauses the tracker: the schedule asked for nothing and keeps running.\nOwner only.\n", "tags": [ "Trackers" ], "x-scope": "write", "x-mcp-tool": "survey_now", "responses": { "201": { "description": "The survey that was just started.", "content": { "application/json": { "schema": { "type": "object", "required": [ "survey" ], "properties": { "survey": { "$ref": "#/components/schemas/Survey" } } } } } }, "200": { "description": "A survey of this tracker was already running: it is the one that comes back.", "content": { "application/json": { "schema": { "type": "object", "required": [ "survey" ], "properties": { "survey": { "$ref": "#/components/schemas/Survey" } } } } } }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "409": { "description": "The refusal names the move that unblocks: `tracker_not_active` (start it first),\n`tracker_archived` (bring it back first), `already_starting` (another call is starting\none right now, nothing spent).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/pause": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "post": { "operationId": "pauseTracker", "summary": "Pause the measurement", "description": "Pauses the measurement; the series is kept. Recorded as a `manual` pause, which a top-up\nleaves as it is: it waits for `POST /trackers/{id}/start`. Owner only.\n", "tags": [ "Trackers" ], "x-scope": "write", "x-mcp-tool": "pause_tracker", "responses": { "200": { "description": "The tracker, paused.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tracker" ], "properties": { "tracker": { "$ref": "#/components/schemas/Tracker" } } } } } }, "409": { "description": "`not_active`: only an active tracker can be paused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/archive": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "post": { "operationId": "archiveTracker", "summary": "File a tracker away, or bring it back", "description": "The body is the STATE you want: omitted it files the tracker away, `{\"archived\": false}`\nbrings it back, and both moves answer the same when replayed. A tracker still measuring\npauses in the same call, so the answer carries `status: \"paused\"` to say it. The sheet and\nthe score series are kept. Owner only.\n", "tags": [ "Trackers" ], "x-scope": "write", "x-mcp-tool": "archive_tracker", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveState" } } } }, "responses": { "200": { "description": "The tracker, filed away or back to the list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tracker" ], "properties": { "tracker": { "$ref": "#/components/schemas/Tracker" } } } } } }, "422": { "description": "`invalid_tracker`: `archived` must be a boolean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/surveys": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "get": { "operationId": "listSurveys", "summary": "List the surveys of the tracker chain", "description": "The surveys of the tracker chain, newest first. `panel_version` is the tracker version that\nran each one (the series spans versions), and `billed_analysts` lists the AI analysts\nreserved on that survey, what the credit hold covered.\n", "tags": [ "Results" ], "x-scope": "read", "responses": { "200": { "description": "The surveys of the chain.", "content": { "application/json": { "schema": { "type": "object", "required": [ "surveys" ], "properties": { "surveys": { "type": "array", "items": { "$ref": "#/components/schemas/Survey" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/scores": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "get": { "operationId": "getResults", "summary": "Read the score series", "description": "The score series, one row per analyst, keyword, engine, version and period.\n", "tags": [ "Results" ], "x-scope": "read", "x-mcp-tool": "get_results", "parameters": [ { "name": "analyst", "in": "query", "required": false, "description": "One of the analysts that carry a score. The `custom_prompt` analyst yields a text note\nper response, so it is read through `GET /trackers/{id}/responses`.\n", "schema": { "type": "string", "enum": [ "keyword_presence", "share_of_voice", "sentiment" ] } }, { "name": "engine", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Engine" } } ], "responses": { "200": { "description": "The score series.", "content": { "application/json": { "schema": { "type": "object", "required": [ "scores" ], "properties": { "scores": { "type": "array", "items": { "$ref": "#/components/schemas/Score" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/responses": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "get": { "operationId": "getResponses", "summary": "Read the raw answers of one engine", "description": "The answers that succeeded, in surveys that completed. Each one carries the text the engine\nwrote, the sources it cited, `uncited_sources`, the pages it read to write the answer, and\n`searched`, whether it went to the web (`null` when undetermined, for answers measured before\nthe field existed).\n", "tags": [ "Results" ], "x-scope": "read", "x-mcp-tool": "get_responses", "parameters": [ { "name": "engine", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Engine" } }, { "name": "q", "in": "query", "required": false, "description": "Keeps the answers whose text carries this wording.", "schema": { "type": "string" } }, { "name": "question", "in": "query", "required": false, "description": "Keeps the answers to this question.", "schema": { "type": "string" } }, { "name": "survey", "in": "query", "required": false, "description": "A survey id of this chain.", "schema": { "type": "string", "format": "uuid" } }, { "name": "tone", "in": "query", "required": false, "description": "The answers where the sentiment analyst judged a keyword mention with that tone, so a\nweek's negative answers come back in one call.\n", "schema": { "$ref": "#/components/schemas/MentionSentiment" } }, { "name": "include", "in": "query", "required": false, "description": "`raw` adds the full engine payload as `raw_response`.", "schema": { "type": "string", "enum": [ "raw" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "One page of answers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "responses", "pagination" ], "properties": { "responses": { "type": "array", "items": { "$ref": "#/components/schemas/EngineResponse" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/discoveries": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "get": { "operationId": "listKeywordDiscoveries", "summary": "List the discovered keyword suggestions", "description": "The current suggestions, plus `dismissed`, the domains this tracker has set aside, so what\nwas refused stays readable and a change of mind is one call away. Nothing is ever added on\nits own: relay the suggestions to the person, the decision is theirs.\n", "tags": [ "Keyword discovery" ], "x-scope": "read", "x-mcp-tool": "list_keyword_discoveries", "responses": { "200": { "description": "The suggestions and the domains set aside.", "content": { "application/json": { "schema": { "type": "object", "required": [ "discoveries", "dismissed" ], "properties": { "discoveries": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordDiscovery" } }, "dismissed": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/discoveries/accept": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "post": { "operationId": "acceptKeywordDiscovery", "summary": "Accept a suggestion, or a batch", "description": "Turns the domains into tracked keywords, in place, within the keyword cap. Send `domain` for\none or `domains` for several, never both; the answer echoes the shape you sent, `keyword` for\none and `keywords` for a batch, plus the updated tracker. A batch is all or nothing.\nManager or above.\n", "tags": [ "Keyword discovery" ], "x-scope": "write", "x-mcp-tool": "accept_keyword_discovery", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOrDomains" } } } }, "responses": { "200": { "description": "The keywords now tracked, and the tracker as it stands.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tracker" ], "properties": { "keyword": { "type": "string", "description": "Present when `domain` was sent." }, "keywords": { "type": "array", "description": "Present when `domains` was sent.", "items": { "type": "string" } }, "tracker": { "$ref": "#/components/schemas/Tracker" } } } } } }, "409": { "description": "`keyword_cap_reached`, which carries the cap as `keyword_cap`, or `not_editable` on a\nretired version.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "A domain is not among the current suggestions of the tracker; `domains` lists the\noffenders.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/discoveries/dismiss": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "post": { "operationId": "dismissKeywordDiscovery", "summary": "Dismiss a suggestion, or a batch", "description": "Retires the domains: never proposed again on this tracker. Dismissing an already dismissed\ndomain answers the same. Manager or above.\n", "tags": [ "Keyword discovery" ], "x-scope": "write", "x-mcp-tool": "dismiss_keyword_discovery", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOrDomains" } } } }, "responses": { "200": { "description": "The domains now set aside, in the shape that was sent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dismissed" ], "properties": { "dismissed": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } } } }, "409": { "description": "`not_editable`: a retired tracker version is revision history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "A domain is not among the current suggestions; `domains` lists the offenders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/trackers/{id}/discoveries/restore": { "parameters": [ { "$ref": "#/components/parameters/TrackerId" } ], "post": { "operationId": "restoreKeywordDiscovery", "summary": "Restore a dismissed domain, or a batch", "description": "Takes a domain back out of `dismissed`, so discovery may surface it again. Idempotent:\nrestoring a domain that was not dismissed leaves it eligible. Manager or above.\n", "tags": [ "Keyword discovery" ], "x-scope": "write", "x-mcp-tool": "restore_keyword_discovery", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainOrDomains" } } } }, "responses": { "200": { "description": "The domains now eligible again, in the shape that was sent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "restored" ], "properties": { "restored": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } } } } }, "409": { "description": "`not_editable`: a retired tracker version is revision history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects": { "get": { "operationId": "listProjects", "summary": "List the projects of the account", "description": "The folders trackers are filed under: one per client for an agency, one per website or brand\nfor an organization. The folders still in use come first, then the ones filed away. A tracker\nwithout a project lives under the virtual `Default` project, which has no row and no id.\n", "tags": [ "Projects" ], "x-scope": "read", "x-mcp-tool": "list_projects", "responses": { "200": { "description": "The projects of the account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createProject", "summary": "Create a project", "description": "Creates a folder. The canon carried at creation is recorded as version 1. When the name is\nalready taken (case, accents and spacing do not make two different names), `409\nproject_exists` carries the existing project, so reuse its id. Manager or above.\n", "tags": [ "Projects" ], "x-scope": "write", "x-mcp-tool": "create_project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The name of the folder, unique per account." } } }, { "$ref": "#/components/schemas/CanonFields" } ] } } } }, "responses": { "201": { "description": "The project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEnvelope" } } } }, "409": { "description": "`project_exists`: the answer carries the existing project as `project`.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } } } ] } } } }, "422": { "description": "`invalid_name` or `invalid_canon`: the message names what it refuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "patch": { "operationId": "renameProject", "summary": "Rename a project", "description": "The folder keeps its id, its canon, its trackers, its surfaces and its logbook: the name\nshown is the only thing that changes. Sending the name it already carries answers the same.\nManager or above.\n", "tags": [ "Projects" ], "x-scope": "write", "x-mcp-tool": "rename_project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "The project, renamed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEnvelope" } } } }, "409": { "description": "`project_exists`: another project of the account already goes by this name, and the\nanswer carries it as `project`.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" } } } ] } } } }, "422": { "description": "`invalid_name`: a non-empty name, of at most the length the message names.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/canon": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "getCanon", "summary": "Read the brand canon and its history", "description": "`canon` is the current wording and `canon_version` its number. `history` carries every\nversion, newest first, each with the fields it touched, before and after: read it to\nRE-PROPAGATE a revision, since the logbook says which keys moved and when, and this says what\nthey moved from and to.\n", "tags": [ "Projects" ], "x-scope": "read", "x-mcp-tool": "get_canon", "responses": { "200": { "description": "The canon of the project and the history of its revisions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "project", "canon", "canon_version", "history" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "project": { "type": "string" }, "canon": { "$ref": "#/components/schemas/Canon" }, "canon_version": { "type": [ "integer", "null" ], "description": "The number of the current version, null when the canon was never posted." }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/CanonVersion" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateProjectCanon", "summary": "Revise the brand canon", "description": "Field by field: a sent field replaces the current wording (an empty string or `null` clears\nit), an omitted field is kept as is. Any actual change records the next canon version,\nimmutable, and `version_created` says whether one was recorded; sending identical wording\nrecords nothing. The canon is meant to stay stable, so confirm with the person before\ncalling. Manager or above.\n", "tags": [ "Projects" ], "x-scope": "write", "x-mcp-tool": "update_project_canon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonFields" } } } }, "responses": { "200": { "description": "The project as it now stands, and whether a version was recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "project", "version_created" ], "properties": { "project": { "$ref": "#/components/schemas/Project" }, "version_created": { "type": "boolean" } } } } } }, "422": { "description": "`invalid_canon`: a field is empty where it must not be, or past its cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/archive": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "post": { "operationId": "archiveProject", "summary": "File a project away, or bring it back", "description": "The body is the STATE you want: omitted it files the project away, `{\"archived\": false}`\nbrings it back, and both moves answer the same when replayed. Nothing cascades: the trackers\nfiled under it keep their status and keep measuring, and the answer carries `tracker_count`,\nhow many are still filed under it. Manager or above.\n", "tags": [ "Projects" ], "x-scope": "write", "x-mcp-tool": "archive_project", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveState" } } } }, "responses": { "200": { "description": "The project, filed away or back in use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectEnvelope" } } } }, "422": { "description": "`invalid_project`: `archived` must be a boolean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/link-targets": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "getLinkTargets", "summary": "Read the addresses of the brand a third-party link can point to", "description": "`derived` is what is already covered from work done elsewhere, each row with its `source`:\n`canon` (the canonical website) or `surface` (a page of the surface registry). `free` is what\nhas been set on the project on top of those. Read it before setting anything: an address\nalready derived needs no entry of its own.\n", "tags": [ "Projects" ], "x-scope": "read", "x-mcp-tool": "get_link_targets", "responses": { "200": { "description": "The link targets of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTargets" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "operationId": "setLinkTargets", "summary": "Set the free addresses of the brand", "description": "The addresses that are neither the canon website nor a surface: a satellite domain kept\noutside the registry, a tracking link, a partner page. They are set ONCE for the project and\nserve every line of the corroboration registry, present and future. The list REPLACES the\nprevious one, and the answer returns what the project now holds, derived addresses included.\nAn empty list keeps the derived ones. Manager or above.\n", "tags": [ "Projects" ], "x-scope": "write", "x-mcp-tool": "set_link_targets", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "link_targets" ], "properties": { "link_targets": { "type": "array", "description": "The full list of the free addresses, as absolute http(s) URLs.", "items": { "type": "string", "format": "uri" } } } } } } }, "responses": { "200": { "description": "The link targets the project now holds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkTargets" } } } }, "422": { "description": "`invalid_link_targets`: the message says what the list takes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/surfaces": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "listSurfaces", "summary": "List the surface registry of a project", "description": "The pages about the brand where the customer has the final say, each with the derived canon\nstatus of the surface and the measured authority of the domain it sits on.\n", "tags": [ "Surfaces" ], "x-scope": "read", "x-mcp-tool": "list_surfaces", "parameters": [ { "name": "sort", "in": "query", "required": false, "description": "`registry`, the default, orders by shown name, the order where a known line is found\nagain; `authority` orders by the measured authority of the domain, the most read first.\nIt orders and never filters: every surface stays in the answer.\n", "schema": { "type": "string", "enum": [ "registry", "authority" ] } }, { "name": "deleted", "in": "query", "required": false, "description": "`only` lists what is out of the registry, most recently taken out first. Omitted, the\nread carries the registry alone.\n", "schema": { "type": "string", "enum": [ "only" ] } } ], "responses": { "200": { "description": "The surfaces of the project.", "content": { "application/json": { "schema": { "type": "object", "required": [ "surfaces" ], "properties": { "surfaces": { "type": "array", "items": { "$ref": "#/components/schemas/Surface" } } } } } } }, "422": { "description": "`invalid_sort` or `invalid_filter`: the message names the accepted values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createSurface", "summary": "Register a surface", "description": "Registers one from its `url` alone: the `type` and the `label` are DERIVED from the address,\nso an agent has no superfluous decision to make. Send `type` or `label` only to correct a\nderivation. The surface is born never aligned. Manager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "create_surface", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The exact page, absolute http(s)." }, "type": { "$ref": "#/components/schemas/SurfaceType" }, "label": { "type": [ "string", "null" ] }, "languages": { "type": "array", "description": "Short language codes, like `[\"en\", \"pt-br\"]`. They are the columns of the checklist.", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "201": { "description": "The surface, registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "422": { "description": "`invalid_type` (the message lists the catalogue) or `invalid_surface`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/surfaces/{id}": { "parameters": [ { "$ref": "#/components/parameters/SurfaceId" } ], "patch": { "operationId": "updateSurface", "summary": "Update the registry sheet of a surface", "description": "Only the fields you send change, and a sent `languages` list replaces the previous one.\n`label` and `notes` clear on an empty string or `null`; the `url` never clears, so `null`\nleaves it as it was. Languages ARE the columns of the checklist, so a sheet edit can move\nwhich cells are read: the columns that leave the model come back in\n`dropped_checklist_columns`, always present, and their cells stay stored. No journal line is\never written here. Manager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "update_surface", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "type": { "$ref": "#/components/schemas/SurfaceType" }, "label": { "type": [ "string", "null" ] }, "languages": { "type": "array", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "The surface, and the checklist columns that left the model.", "content": { "application/json": { "schema": { "type": "object", "required": [ "surface", "dropped_checklist_columns" ], "properties": { "surface": { "$ref": "#/components/schemas/Surface" }, "dropped_checklist_columns": { "type": "array", "items": { "$ref": "#/components/schemas/DroppedChecklistColumn" } } } } } } }, "422": { "description": "`invalid_surface` or `invalid_type`, and nothing changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteSurface", "summary": "Take a surface out of the registry", "description": "The surface leaves the registry and everything derived from it: the canon statuses, the quest\nfile, the counts, the curve annotations. Its sheet and its alignment journal are kept as they\nare, and `POST /surfaces/{id}/restore` brings the surface back with them. Idempotent.\nManager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "delete_surface", "responses": { "200": { "description": "The surface, out of the registry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/surfaces/{id}/restore": { "parameters": [ { "$ref": "#/components/parameters/SurfaceId" } ], "post": { "operationId": "restoreSurface", "summary": "Bring a surface back to the registry", "description": "Brings it back with its sheet and its alignment journal. Idempotent. Manager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "restore_surface", "responses": { "200": { "description": "The surface, back in the registry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/surfaces/{id}/checklist": { "parameters": [ { "$ref": "#/components/parameters/SurfaceId" } ], "patch": { "operationId": "tickSurfaceChecklist", "summary": "Verify, set aside or clear checklist cells", "description": "Three moves per cell. VERIFY (`done` true, or nothing sent): the item is constated on the\npage, and a canon-kind item is stamped with the current version and wording. SET ASIDE\n(`dismissed` true plus a short `reason`): the item does not apply on THIS surface; it leaves\nthe denominator, survives canon revisions, and is undone by sending `dismissed` false. CLEAR\n(`done` false): the cell returns to blank. Only the cells you send change. The batch is all\nor nothing, so a verification pass is never half recorded. The aligned status derives from\nthe cells of `checklist.required`. Manager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "tick_surface_checklist", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ticks" ], "properties": { "ticks": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ChecklistTick" } } } } } } }, "responses": { "200": { "description": "The surface, with the checklist as it now reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "409": { "description": "`no_canon` (a canon cell has nothing to restate: set the canon, then tick again),\n`not_a_surface` (setting aside the last canon cell), or `surface_deleted` (bring the\nsurface back first).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`invalid_checklist`: unknown item, unknown language, a language on a site-wide item, or a\nset-aside without reason. The message says what to send, and not a single tick is written.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/surfaces/{id}/checks": { "parameters": [ { "$ref": "#/components/parameters/SurfaceId" } ], "post": { "operationId": "addSurfaceCheck", "summary": "Add a check of your own to the checklist of a surface", "description": "A requirement the customer holds on THAT page, in their words, REQUIRED for it to count as\naligned. `label` is the only field due. `restates_canon` is the one judgement to make: true\nwhen the check restates the WORDING of the canon, so its verification perishes when the\nwording moves; false, the default, when it constates anything else. Sending the same label\nagain returns the check already there and brings it back from the trash if it slept there\n(`201` on creation, `200` otherwise). A surface holds up to twenty checks of your own.\nManager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "add_surface_check", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The wording of the check. The key derives from it at birth and then freezes." }, "scope": { "allOf": [ { "$ref": "#/components/schemas/ChecklistScope" } ], "description": "`language`, the default, is one cell per language of the surface; `site` one cell for the whole site." }, "restates_canon": { "type": "boolean", "default": false } } } } } }, "responses": { "201": { "description": "The surface, and the key of the check that was added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceCheckEnvelope" } } } }, "200": { "description": "The check already existed under this label: the surface and its key come back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceCheckEnvelope" } } } }, "409": { "description": "`check_cap_reached`, `duplicate_check` or `surface_deleted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`invalid_check`: the message names the field it refuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/surfaces/{id}/checks/{key}": { "parameters": [ { "$ref": "#/components/parameters/SurfaceId" }, { "$ref": "#/components/parameters/CheckKey" } ], "patch": { "operationId": "updateSurfaceCheck", "summary": "Correct a check of your own", "description": "Its label, and whether it restates the canon. The key never moves, being the coordinate of\nthe cells already recorded, so renaming keeps every tick. Manager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "update_surface_check", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": [ "string", "null" ] }, "restates_canon": { "type": [ "boolean", "null" ], "description": "Omitted or null, it is kept as is." } } } } } }, "responses": { "200": { "description": "The surface, with the check as it now reads.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "409": { "description": "`duplicate_check` or `surface_deleted`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`invalid_check`: the message names the field it refuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteSurfaceCheck", "summary": "Take a check of your own out of the checklist", "description": "It leaves the checklist and stops holding the page short of aligned, while the definition and\nits cells are kept, read back in `checklist.custom` with `deleted` true. Manager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "delete_surface_check", "responses": { "200": { "description": "The surface, with the check out of the checklist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "409": { "description": "`surface_deleted`: bring the surface back first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`unknown_check`, or an unknown surface.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/surfaces/{id}/checks/{key}/restore": { "parameters": [ { "$ref": "#/components/parameters/SurfaceId" }, { "$ref": "#/components/parameters/CheckKey" } ], "post": { "operationId": "restoreSurfaceCheck", "summary": "Bring a check of your own back to the checklist", "description": "Brings it back with the cells it had. Manager or above.", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "restore_surface_check", "responses": { "200": { "description": "The surface, with the check back in the checklist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "409": { "description": "`surface_deleted`: bring the surface back first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "`unknown_check`, or an unknown surface.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/surfaces/{id}/convert-to-corroboration": { "parameters": [ { "$ref": "#/components/parameters/SurfaceId" } ], "post": { "operationId": "convertSurfaceToCorroboration", "summary": "Move a page to the corroboration registry", "description": "For a line filed on the wrong side, or a page whose final say moved to someone else. Nothing\nis retyped: `url`, `label` and `notes` travel, and the publication date stays unknown rather\nthan guessed. The surface goes to the trash with its alignment journal, and the reverse move\nexists, so a replay finds the same line instead of duplicating it (`201` on creation, `200`\nwhen the page already slept in the registry and was put back live). Manager or above.\n", "tags": [ "Surfaces" ], "x-scope": "write", "x-mcp-tool": "convert_surface_to_corroboration", "responses": { "201": { "description": "The corroboration, recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorroborationEnvelope" } } } }, "200": { "description": "The corroboration already existed and was put back live.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorroborationEnvelope" } } } }, "422": { "description": "`own_domain`: the own site of the brand stays a surface. The other refusals of the\nregistry answer with their own slug.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/corroborations": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "listCorroborations", "summary": "List the corroboration registry of a project", "description": "The pages about the brand where someone else has the final say, each with its exact address,\nlive ones first. Recording is DECLARING: a corroboration carries its `domain` as a plain\nstring, and it can sit on a domain no survey has ever cited. To see whether that source is on\nthe Atlas, search it with `GET /sources?domain=`.\n", "tags": [ "Corroborations" ], "x-scope": "read", "x-mcp-tool": "list_corroborations", "responses": { "200": { "description": "The corroborations of the project.", "content": { "application/json": { "schema": { "type": "object", "required": [ "corroborations" ], "properties": { "corroborations": { "type": "array", "items": { "$ref": "#/components/schemas/Corroboration" } } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createCorroboration", "summary": "Record a corroboration", "description": "Records one from its `url` alone, the exact page and never the home page of the site: the\n`domain` and the `label` are DERIVED from the address. Record a page you have actually read:\nit is a statement of fact, so confirm with the person first. Manager or above.\n", "tags": [ "Corroborations" ], "x-scope": "write", "x-mcp-tool": "create_corroboration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The exact page, absolute http(s)." }, "label": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "published_on": { "type": [ "string", "null" ], "format": "date", "description": "The day the page was PUBLISHED, as `YYYY-MM-DD`, null when unknown rather than guessed." }, "request_channel": { "$ref": "#/components/schemas/RequestChannel" } } } } } }, "responses": { "201": { "description": "The corroboration, recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorroborationEnvelope" } } } }, "409": { "description": "`duplicate`: this page is already in the registry of this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`unplaceable_url` (the address has no registrable domain), `own_domain` (this is the own\nsite of the brand: use `POST /projects/{id}/surfaces`), or `invalid_corroboration`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/corroborations/monitoring": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "post": { "operationId": "setRegistryMonitoring", "summary": "Set the watching cadence of the whole registry", "description": "Sets the cadence in one move, `off` to stop it. Arming covers the live readable lines,\nstopping never refuses, and the answer carries the count covered, so nothing has to be\nre-listed. Manager or above.\n", "tags": [ "Corroborations" ], "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monitoring": { "$ref": "#/components/schemas/MonitoringCadence" } } } } } }, "responses": { "200": { "description": "The cadence now set, and how many lines it covered.", "content": { "application/json": { "schema": { "type": "object", "required": [ "monitoring", "corroborations" ], "properties": { "monitoring": { "$ref": "#/components/schemas/MonitoringCadence" }, "corroborations": { "type": "integer", "description": "How many lines of the registry the move covered." } } } } } }, "422": { "description": "`invalid_monitoring`: the message lists the catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/corroborations/{id}": { "parameters": [ { "$ref": "#/components/parameters/CorroborationId" } ], "patch": { "operationId": "updateCorroboration", "summary": "Update the sheet of a corroboration", "description": "Only the fields you send change. `label` and `notes` clear on an empty string or `null`, and\na cleared label goes back to the derived one; `published_on` clears the same way; the `url`\nnever clears, so `null` leaves it as it was. Correcting the `url` ALWAYS recomputes the\n`domain`. `monitoring` arms the automatic watching of the line: it states a STATE, so\nre-sending a value changes nothing, and it evaluates on the sheet as it lands. Manager or\nabove.\n", "tags": [ "Corroborations" ], "x-scope": "write", "x-mcp-tool": "update_corroboration", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": [ "string", "null" ], "format": "uri" }, "label": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "published_on": { "type": [ "string", "null" ], "format": "date" }, "request_channel": { "$ref": "#/components/schemas/RequestChannel" }, "monitoring": { "$ref": "#/components/schemas/MonitoringCadence" } } } } } }, "responses": { "200": { "description": "The corroboration as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorroborationEnvelope" } } } }, "409": { "description": "`corroboration_archived` or `page_not_readable`: watching applies to a live line whose\npage reads, and `off` is always accepted.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`invalid_corroboration`, `unplaceable_url` or `own_domain`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/corroborations/{id}/verify": { "parameters": [ { "$ref": "#/components/parameters/CorroborationId" } ], "post": { "operationId": "verifyCorroboration", "summary": "Read the page now, on demand", "description": "One pass refreshes the two findings of the line, dated, and every line carries the latest\nresult as `page_check`. On the MENTION: the passage around the brand is archived on the line,\nand when a change has been found, `excerpt_before` carries the passage as it stood before\n`changed_at`. On the LINK: every link of the page towards an address of the brand, each with\nits rel tokens, its anchor text and its target. Free of charge. Manager or above.\n", "tags": [ "Corroborations" ], "x-scope": "write", "x-mcp-tool": "verify_corroboration", "responses": { "200": { "description": "The corroboration, with the findings of the pass.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorroborationEnvelope" } } } }, "409": { "description": "`corroboration_archived`: put the line back live with `POST /corroborations/{id}/archive`\nand `{\"archived\": false}` to check it again.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/corroborations/{id}/archive": { "parameters": [ { "$ref": "#/components/parameters/CorroborationId" } ], "post": { "operationId": "archiveCorroboration", "summary": "Record that the page is gone, or put it back live", "description": "The body is the STATE you want: omitted it records that the page is gone, `{\"archived\":\nfalse}` puts it back live, and replaying it never undoes what it just did. The line and its\nhistory stay, because \"they talked about us from March to July\" is information. A recording\nmistake is fixed with a PATCH. Manager or above.\n", "tags": [ "Corroborations" ], "x-scope": "write", "x-mcp-tool": "archive_corroboration", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveState" } } } }, "responses": { "200": { "description": "The corroboration, taken down or back live.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorroborationEnvelope" } } } }, "422": { "description": "`invalid_corroboration`: `archived` must be a boolean.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/corroborations/{id}/convert-to-surface": { "parameters": [ { "$ref": "#/components/parameters/CorroborationId" } ], "post": { "operationId": "convertCorroborationToSurface", "summary": "Move a page to the surface registry", "description": "When the customer has, or takes, the final say on it: their own profile filed on the wrong\nside, or a source that became a reliable channel. Nothing is retyped: `url`, `label` and\n`notes` travel, the publication date is copied into the notes, the type derives from the\naddress. A replay finds the same line instead of duplicating it (`201` on creation, `200`\nwhen the page already slept in the surface registry and was brought back). Manager or above.\n", "tags": [ "Corroborations" ], "x-scope": "write", "x-mcp-tool": "convert_corroboration_to_surface", "responses": { "201": { "description": "The surface, registered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "200": { "description": "The surface already existed and was brought back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurfaceEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/corroboration-candidates": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "listCorroborationCandidates", "summary": "List the pages an engine showed the brand on", "description": "The MENTIONS an engine has shown the brand in: pages found in the text the engine itself\nreturned next to each address, read from raw payloads already in store over the latest\nsurveys (`surveys_scanned` says how many). Each row carries no id, because the list is\nrecomputed on every read. `matched_by` is the strength of the proof, and `suggested` names\nthe registry the filing is proposed in: it is a suggestion, never a filing, and the customer\ndecides. To accept one, record it with `POST /projects/{id}/corroborations`.\n", "tags": [ "Corroborations" ], "x-scope": "read", "x-mcp-tool": "list_corroboration_candidates", "responses": { "200": { "description": "The candidates, and how many surveys were read.", "content": { "application/json": { "schema": { "type": "object", "required": [ "candidates", "surveys_scanned" ], "properties": { "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/CorroborationCandidate" } }, "surveys_scanned": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/corroboration-candidates/dismiss": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "post": { "operationId": "dismissCorroborationCandidate", "summary": "Refuse a candidate by its address", "description": "That page is never proposed again for this project. Nothing is created or deleted, and the\ncall is idempotent. Manager or above.\n", "tags": [ "Corroborations" ], "x-scope": "write", "x-mcp-tool": "dismiss_corroboration_candidate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "The address of the candidate, exactly as listed." } } } } } }, "responses": { "200": { "description": "The address now refused.", "content": { "application/json": { "schema": { "type": "object", "required": [ "dismissed" ], "properties": { "dismissed": { "type": "string" } } } } } }, "422": { "description": "`invalid_corroboration`: `url` is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/projects/{id}/logbook": { "parameters": [ { "$ref": "#/components/parameters/ProjectId" } ], "get": { "operationId": "getLogbook", "summary": "Read the logbook of a project", "description": "The composed timeline, newest first. Suite moves are derived from the product itself (the\ncanon moved to a version, a surface was marked aligned, a corroboration was recorded): they\nappear on their own, carry no id, and are read-only. Manual entries are the actions the\ncustomer records, freely editable. Every move also lands as an annotation on the citation\ncurves of the trackers of the project.\n", "tags": [ "Logbook" ], "x-scope": "read", "x-mcp-tool": "get_logbook", "parameters": [ { "name": "source", "in": "query", "required": false, "description": "`tool` for suite moves, `manual` for logbook entries.", "schema": { "type": "string", "enum": [ "tool", "manual" ] } }, { "name": "category", "in": "query", "required": false, "description": "Matches manual entries, which are the ones that carry a category.", "schema": { "$ref": "#/components/schemas/LogbookCategory" } }, { "name": "quest_id", "in": "query", "required": false, "description": "The dated trail of one quest. Matches manual entries, which are the ones that carry a quest.", "schema": { "type": "string", "format": "uuid" } }, { "name": "deleted", "in": "query", "required": false, "description": "`only` lists the trash, most recently taken out first. It carries recorded entries only,\nso it goes without `source`, `category` and `quest_id`.\n", "schema": { "type": "string", "enum": [ "only" ] } } ], "responses": { "200": { "description": "The logbook of the project.", "content": { "application/json": { "schema": { "type": "object", "required": [ "logbook" ], "properties": { "logbook": { "type": "array", "items": { "$ref": "#/components/schemas/LogbookItem" } } } } } } }, "422": { "description": "`invalid_filter`, `invalid_category`, `invalid_source` or `invalid_quest`: the message\nnames the accepted values.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createLogbookEntry", "summary": "Record an action in the logbook", "description": "`occurred_at` is the date the action HAPPENED, past dates welcome: when the person says\n\"yesterday\" or \"last week\", compute that date and pass it. The call is idempotent on\n`(project, quest_id, label, occurred_at)`: send it again and you get the entry already\nrecorded, with `200` instead of `201`. When the twin is one that had been taken out, it comes\nback rather than being written a second time, and `restored` is `true` in the answer.\n", "tags": [ "Logbook" ], "x-scope": "write", "x-mcp-tool": "create_logbook_entry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "category", "label" ], "properties": { "category": { "$ref": "#/components/schemas/LogbookCategory" }, "label": { "type": "string", "description": "A short wording: it is what the annotation shows." }, "occurred_at": { "type": "string", "description": "ISO 8601 date or datetime, read as UTC without an offset. Omitted, now." }, "notes": { "type": [ "string", "null" ] }, "quest_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The quest of the same project the action moves forward." } } } } } }, "responses": { "201": { "description": "The entry, recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogbookEntryEnvelope" } } } }, "200": { "description": "The same entry was already recorded, or was brought back from the trash.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogbookEntryEnvelope" } } } }, "422": { "description": "`invalid_category`, `invalid_date`, `invalid_entry` or `invalid_quest`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/logbook/{id}": { "parameters": [ { "$ref": "#/components/parameters/LogbookEntryId" } ], "patch": { "operationId": "updateLogbookEntry", "summary": "Correct a manual entry", "description": "Field by field: only the fields you send change (empty `notes` clear them; the `label` never\nclears, so `null` leaves it as it was). `quest_id` files an entry under a quest after the\nfact, and `null` files it back under the project alone: it states a state, so it replays\nsafely both ways.\n", "tags": [ "Logbook" ], "x-scope": "write", "x-mcp-tool": "update_logbook_entry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/LogbookCategory" }, "label": { "type": [ "string", "null" ] }, "occurred_at": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "quest_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "responses": { "200": { "description": "The entry as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogbookEntryEnvelope" } } } }, "422": { "description": "`invalid_entry`, `invalid_category`, `invalid_date` or `invalid_quest`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteLogbookEntry", "summary": "Take a manual entry out of the logbook", "description": "The entry leaves the logbook, along with the annotation it placed on the curves, and waits in\nthe trash: `GET /projects/{id}/logbook?deleted=only` lists what is out and `POST\n/logbook/{id}/restore` brings one back. Idempotent. Do it when the person asked for it: it is\ntheir logbook.\n", "tags": [ "Logbook" ], "x-scope": "write", "x-mcp-tool": "delete_logbook_entry", "responses": { "200": { "description": "The entry is out of the logbook.", "content": { "application/json": { "schema": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "const": true } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/logbook/{id}/restore": { "parameters": [ { "$ref": "#/components/parameters/LogbookEntryId" } ], "post": { "operationId": "restoreLogbookEntry", "summary": "Bring an entry back to the logbook", "description": "Brings it back with its annotation. Idempotent.", "tags": [ "Logbook" ], "x-scope": "write", "x-mcp-tool": "restore_logbook_entry", "responses": { "200": { "description": "The entry, back in the logbook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogbookEntryEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/quests": { "get": { "operationId": "listQuests", "summary": "Read the quest file", "description": "What there is to do for the GEO work, newest first, every active project by default. Each\nquest carries `journal_entries` and `last_entry_at`, how many actions were recorded against\nit and when the last one happened; the entries themselves are read with `GET\n/projects/{id}/logbook?quest_id=`. The open file also carries `pending`, the work the\nmeasurement itself is holding for review, composed on every read so it empties on its own as\nthe moves are made.\n", "tags": [ "Quests" ], "x-scope": "read", "x-mcp-tool": "list_quests", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "`open` by default; `done` and `dismissed` read the closed history.", "schema": { "$ref": "#/components/schemas/QuestStatus" } }, { "name": "project_id", "in": "query", "required": false, "description": "Scopes the file to one project.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The quest file. `pending` comes with the open file; on the project-scoped read it also\ncarries `corroboration_candidates`.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "quests" ], "properties": { "quests": { "type": "array", "items": { "$ref": "#/components/schemas/Quest" } }, "pending": { "$ref": "#/components/schemas/QuestPending" } } } } } }, "422": { "description": "`invalid_status` or `invalid_project`: the message lists the catalogue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createQuest", "summary": "Add a quest", "description": "`project_id` travels in the body: the file is account-wide, the project is data. The call is\nidempotent on `(project, title)` while the quest is open: send it again and you get the quest\nalready in the file, with `200` instead of `201`. A closed quest with the same title does not\nblock: doing the move again later is a new quest with its own history.\n", "tags": [ "Quests" ], "x-scope": "write", "x-mcp-tool": "create_quest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "title" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "description": "A short wording of the move: it is what the file shows." }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "201": { "description": "The quest, added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestEnvelope" } } } }, "200": { "description": "A quest with this title is already open in this project: it is the one that comes back.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestEnvelope" } } } }, "422": { "description": "`invalid_quest` or `invalid_project`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/quests/{id}": { "parameters": [ { "$ref": "#/components/parameters/QuestId" } ], "patch": { "operationId": "updateQuest", "summary": "Correct a quest", "description": "Field by field: only the fields you send change (empty `notes` clear them; the `title` never\nclears, so `null` leaves it as it was). The status moves through its own calls.\n", "tags": [ "Quests" ], "x-scope": "write", "x-mcp-tool": "update_quest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "The quest as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestEnvelope" } } } }, "422": { "description": "`invalid_quest`: a field was sent as something other than text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/quests/{id}/complete": { "parameters": [ { "$ref": "#/components/parameters/QuestId" } ], "post": { "operationId": "completeQuest", "summary": "Set a quest done", "description": "The move happened. Replayable; the last move is what the file remembers.", "tags": [ "Quests" ], "x-scope": "write", "x-mcp-tool": "complete_quest", "responses": { "200": { "description": "The quest, done.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/quests/{id}/dismiss": { "parameters": [ { "$ref": "#/components/parameters/QuestId" } ], "post": { "operationId": "dismissQuest", "summary": "Set a quest aside", "description": "Replayable, and the quest stays in the closed history.", "tags": [ "Quests" ], "x-scope": "write", "x-mcp-tool": "dismiss_quest", "responses": { "200": { "description": "The quest, set aside.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/quests/{id}/reopen": { "parameters": [ { "$ref": "#/components/parameters/QuestId" } ], "post": { "operationId": "reopenQuest", "summary": "Put a closed quest back in the file", "description": "Sheet and dates intact, `closed_at` cleared: the same quest resumes, with its own history.\nReplayable.\n", "tags": [ "Quests" ], "x-scope": "write", "x-mcp-tool": "reopen_quest", "responses": { "200": { "description": "The quest, back in the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestEnvelope" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/competitor-scans": { "get": { "operationId": "listCompetitorScans", "summary": "List the competitor scans of the account", "description": "The scans of the account, newest first, without their list of places.", "tags": [ "Competitor scans" ], "x-scope": "read", "x-mcp-tool": "list_competitor_scans", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The competitor scans.", "content": { "application/json": { "schema": { "type": "object", "required": [ "competitor_scans" ], "properties": { "competitor_scans": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorScan" } } } } } } }, "422": { "description": "`invalid_project`: `project_id` must be the UUID of a project of the account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createCompetitorScan", "summary": "Prepare a competitor scan, as a draft", "description": "Prepares a scan on a basket of up to 5 companies of the same market, as a DRAFT: the answer\ncarries the questions it derived for you to read, and the amount it would cost as\n`estimated_cost_minor`. Each subject needs a `website`, since a whole domain found in a page\nis what tells two companies with the same name apart. Three companies or more and the places\nrank by recurrence, by how many of the basket each one covers.\n", "tags": [ "Competitor scans" ], "x-scope": "write", "x-mcp-tool": "create_competitor_scan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "subjects" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "title": { "type": "string", "description": "Omitted, it takes the category, or the name of the project." }, "engine": { "allOf": [ { "$ref": "#/components/schemas/Engine" } ], "description": "The engine the questions are asked to. Omitted, `chatgpt`." }, "language": { "type": "string", "description": "The language the questions are asked in. Omitted, the canonical language of the project, or `en`." }, "country": { "type": [ "string", "null" ] }, "category": { "type": "string", "description": "What qualifies each company in the questions." }, "usage": { "type": "string", "description": "What buyers use it for. Omitted, the category." }, "subjects": { "type": "array", "maxItems": 5, "items": { "type": "object", "required": [ "name", "website" ], "properties": { "name": { "type": "string" }, "website": { "type": "string" } } } }, "templates": { "type": "array", "description": "Which of the four questions each company gets. Omitted, all four.", "items": { "$ref": "#/components/schemas/CompetitorTemplate" } } } } } } }, "responses": { "201": { "description": "The scan, in draft, with the questions it derived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorScanEnvelope" } } } }, "422": { "description": "`invalid_project`, `invalid_engine`, `invalid_template` or `invalid_competitor_scan`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/competitor-scans/{id}": { "parameters": [ { "$ref": "#/components/parameters/CompetitorScanId" } ], "get": { "operationId": "getCompetitorScan", "summary": "Read one scan and its accumulated list of places", "description": "Every place holds `subjects`, the number of the basket corroborated there, its `reach` (the\nway in), the `ai_authority` of the domain, its exact `pages`, and `client_present`, which\nsays whether the account already recorded a corroboration there. The list ACCUMULATES over\nevery check, deduplicated by URL, so `seen_in_checks` counts checks and never citations.\n`controlled` is what each company publishes on its own site, and `rivals` the competitive set\nthe engine names. To act on a place, add a quest with its URL.\n", "tags": [ "Competitor scans" ], "x-scope": "read", "x-mcp-tool": "get_competitor_scan", "responses": { "200": { "description": "The scan, and its report once it has results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "competitor_scan", "report" ], "properties": { "competitor_scan": { "$ref": "#/components/schemas/CompetitorScan" }, "report": { "oneOf": [ { "$ref": "#/components/schemas/CompetitorScanReport" }, { "type": "null" } ] } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateCompetitorScan", "summary": "Reword the questions of a draft, or set its rescan cadence", "description": "`questions` is the list of the ones to KEEP with the text to ask, an omitted `text` keeping\nthe current one; a question of the scan left out of the list is removed, and\n`estimated_cost_minor` follows it. `rescan_cadence` set to `weekly` or `monthly` runs the\nscan again on that cadence, `null` stops it: it states a state, and replays safely both ways.\n", "tags": [ "Competitor scans" ], "x-scope": "write", "x-mcp-tool": "update_competitor_scan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "text": { "type": "string" } } } }, "rescan_cadence": { "oneOf": [ { "type": "string", "enum": [ "weekly", "monthly" ] }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "The scan as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorScanEnvelope" } } } }, "409": { "description": "`already_launched` (a measured scan keeps its questions: prepare another one to ask\nsomething else) or `scan_not_armed` (arm the scan first, the cadence follows the first\ncheck).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`invalid_questions`, `unknown_question`, `no_question` or `invalid_cadence`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/competitor-scans/{id}/start": { "parameters": [ { "$ref": "#/components/parameters/CompetitorScanId" } ], "post": { "operationId": "startCompetitorScan", "summary": "Arm a competitor scan", "description": "The engine is asked and the balance is debited by `estimated_cost_minor`, so name the amount\nto the person first. Replaying it answers with the scan already armed.\n", "tags": [ "Competitor scans" ], "x-scope": "write", "x-mcp-tool": "start_competitor_scan", "responses": { "200": { "description": "The scan, armed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorScanEnvelope" } } } }, "402": { "description": "`insufficient_credits`: the prepaid balance does not cover this scan. Top up, then arm it\nagain.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`no_question`, `no_engine_available` or `already_starting`. Nothing was charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sources": { "get": { "operationId": "listSources", "summary": "List the Atlas of sources", "description": "The map of the sources the AIs cite when they answer your trackers. Every entry is a\nregistrable domain, so `fr.wikipedia.org` and `en.wikipedia.org` are one and the same source.\nThe Atlas you read lists the sources your own surveys surfaced, and it grows as you measure\nmore; the AI Authority scale stays computed across every measurement Epovest runs, which is\nwhat makes a 61 mean the same thing on your Atlas as on anyone else's.\n", "tags": [ "Atlas" ], "x-scope": "read", "x-mcp-tool": "list_sources", "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "Keeps the domains containing that text.", "schema": { "type": "string" } }, { "name": "engine", "in": "query", "required": false, "description": "Keeps the sources that engine has cited at least once.", "schema": { "$ref": "#/components/schemas/Engine" } }, { "name": "sort", "in": "query", "required": false, "description": "`aa_chatgpt`, `aa_claude`, `aa_gemini`, `aa_perplexity`, `aa_mistral` and `aa_grok` each\ngive the ranking of one AI and keep only the sources that AI cites. The others order\nacross all AIs (`detections`, the default), by number of distinct engines (`engines`), by\nmost recent detection (`freshness`) or alphabetically (`domain`).\n", "schema": { "type": "string", "enum": [ "detections", "engines", "freshness", "domain", "aa_chatgpt", "aa_claude", "aa_gemini", "aa_perplexity", "aa_mistral", "aa_grok" ] } }, { "name": "dir", "in": "query", "required": false, "description": "Left out, each sort takes its natural way, strongest first for a ranking and A to Z for\n`domain`. Ascending is what answers \"where am I weakest\".\n", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "project_id", "in": "query", "required": false, "description": "The map of one brand: the UUID of a project of the account, or `default` for the trackers\nfiled under none. Left out, the map covers every tracker of the account.\n", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "One page of the Atlas.", "content": { "application/json": { "schema": { "type": "object", "required": [ "sources", "pagination" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "422": { "description": "`invalid_engine`, `invalid_sort`, `invalid_direction` or `invalid_project`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sources/{id}": { "parameters": [ { "$ref": "#/components/parameters/SourceId" } ], "get": { "operationId": "getSource", "summary": "Read one source by its id", "description": "The same entry the list carries.", "tags": [ "Atlas" ], "x-scope": "read", "x-mcp-tool": "get_source", "responses": { "200": { "description": "The source.", "content": { "application/json": { "schema": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/Source" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/sources/{id}/channels": { "parameters": [ { "$ref": "#/components/parameters/SourceId" } ], "get": { "operationId": "listSourceChannels", "summary": "Read the channels behind a source", "description": "The channels that published the videos the AIs cited when answering your questions. The order\nis the measure: how many of your questions the channel came back on, then videos, then\ncitations, so a channel that answers two of your questions with one well-titled video sits\nabove a busy channel cited twice on the same one. `you_are_there` is read from the\ncorroborations this account has recorded on that channel or on one of its videos.\n", "tags": [ "Atlas" ], "x-scope": "read", "x-mcp-tool": "list_source_channels", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "The UUID of a project of the account, or `default` for the trackers filed under none.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The channels, and the counts the list is drawn from.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceChannels" } } } }, "422": { "description": "`invalid_project`: the message says what `project_id` takes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/account": { "get": { "operationId": "getAccountSettings", "summary": "Read the settings of the account", "description": "The legal name, the billing country, the postal address and the intra-EU VAT number, plus the\nlanguage we write to the account in and the time zone its hours are shown in. Read before you\nwrite: only the fields you send change, so this answer is what tells you the value of\neverything you are leaving alone. `language` and `timezone` always come back with the value\nin force, `en` and `UTC` by default.\n", "tags": [ "Account" ], "x-scope": "read", "x-mcp-tool": "get_account_settings", "responses": { "200": { "description": "The settings of the account.", "content": { "application/json": { "schema": { "type": "object", "required": [ "account" ], "properties": { "account": { "$ref": "#/components/schemas/Account" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "operationId": "updateAccountSettings", "summary": "Change the settings of the account", "description": "Only the fields you send change. `billing_country`, `billing_address` and\n`intra_eu_vat_number` clear when you send `null`; `name`, `language` and `timezone` keep their\nvalue on `null`, so name the language or the time zone you want. A postal address and a VAT\nnumber travel with `billing_country`: send the country in the same call, and the VAT number\ngoes with an EU country. What you write applies to the invoices issued from then on. Writing\nthe billing identity is owner only. Signing in is set up in the app: the email address, the\npassword and the second factor are confirmed there by the person themselves.\n", "tags": [ "Account" ], "x-scope": "write", "x-mcp-tool": "update_account_settings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The legal name printed on the invoices, at most 160 characters." }, "billing_country": { "type": [ "string", "null" ], "description": "An ISO 3166-1 alpha-2 code, like `FR` or `US`." }, "billing_address": { "oneOf": [ { "type": "array", "maxItems": 3, "items": { "type": "string" } }, { "type": "null" } ], "description": "One string per line, three lines of 150 characters at most." }, "intra_eu_vat_number": { "type": [ "string", "null" ], "description": "The two-letter code of an EU member state followed by its national number, like `FR12345678901`." }, "language": { "type": [ "string", "null" ], "enum": [ "en", "fr", "es", "de", "it", "pt", null ] }, "timezone": { "type": [ "string", "null" ], "description": "An IANA identifier, like `Europe/Paris`, `America/New_York` or `UTC`." } } } } } }, "responses": { "200": { "description": "The settings as they now stand.", "content": { "application/json": { "schema": { "type": "object", "required": [ "account" ], "properties": { "account": { "$ref": "#/components/schemas/Account" } } } } } }, "409": { "description": "`no_member`: the account has no active owner whose language and time zone could be set;\nits members are fixed in the app.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`invalid_account`: the message names the field it refuses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/credits": { "get": { "operationId": "getCredits", "summary": "Read the prepaid credit balance", "description": "Epovest is prepaid: measurement debits a credit balance. Credits never expire, and reading\nstays open: an account reads its whole series whenever it comes back, however long it has\nbeen idle, and spends the balance it already has. `suggested_topups` carries three amounts\nderived from the monthly pace of the account, worth one, three and six months of it: take one\nof these when the person leaves the amount to you.\n", "tags": [ "Credits" ], "x-scope": "read", "x-mcp-tool": "get_credits", "responses": { "200": { "description": "The balance, the reservations, and the amounts derived from the pace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Credits" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/credits/topup": { "post": { "operationId": "topupCredits", "summary": "Prepare a top-up and return the hosted payment link", "description": "Emits the top-up invoice and returns the hosted payment page: nothing is charged by the call\nitself. Hand `payment_url` to the person; they approve the amount there, and once they pay,\nthe balance updates on its own and the trackers that ran out of credit resume. The amount\ngoes in one of two units, one per speaker: send exactly one of them, and a key set to `null`\ncounts as absent. Amounts are always in the wallet currency of the account, which `GET\n/credits` gives. The response echoes the amount in both units. Owner only.\n", "tags": [ "Credits" ], "x-scope": "write", "x-mcp-tool": "topup_credits", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": [ "number", "string", "null" ], "description": "Major units of the wallet currency: `50` means 50.00, `12.5` means 12.50. Use it\nwhen the person names the amount, and pass exactly the number they said.\n" }, "amount_minor": { "type": [ "integer", "null" ], "description": "Minor units: `5000` means 50.00. Use it when the person leaves the amount to you:\ntake one of the `suggested_topups[]` of `GET /credits` and pass its `amount_minor`.\n" } } } } } }, "responses": { "200": { "description": "The hosted payment page, and the amount in both units.", "content": { "application/json": { "schema": { "type": "object", "required": [ "payment_url", "amount", "amount_minor", "currency" ], "properties": { "payment_url": { "type": "string", "format": "uri" }, "amount": { "type": "string", "description": "The amount in major units." }, "amount_minor": { "type": "integer" }, "currency": { "type": "string", "description": "The wallet currency, upper case." } } } } } }, "409": { "description": "`email_unverified` (the account owner verifies their email in the app first) or\n`no_billing_contact` (the account has no owner to bill).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`below_min_topup`: the amount is under the floor, given back as `min_topup` and\n`min_topup_minor`.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "min_topup": { "type": "string" }, "min_topup_minor": { "type": "integer" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Read what the account has spent", "description": "`GET /credits` says what is left to spend; this says what has been spent, and on what: the\nledger entries, plus the same amounts by month, by cost line, by project and by tracker. The\namounts outside `by_month` are a cumulative total over `period`, never a monthly figure, so\nquote the period alongside the amount. `this_month_forecast` is the month in progress: report\nit as a forecast, never as spend.\n", "tags": [ "Usage" ], "x-scope": "read", "x-mcp-tool": "get_usage", "parameters": [ { "name": "month", "in": "query", "required": false, "description": "`YYYY-MM` narrows everything to one month.", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, { "name": "type", "in": "query", "required": false, "description": "Narrows `entries[]` alone, since both breakdowns are spend by nature.", "schema": { "type": "string", "enum": [ "in", "out" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "The spend of the period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/support/messages": { "post": { "operationId": "contactSupport", "summary": "Write to the support team", "description": "Reaches the humans behind Epovest: report a problem, suggest an improvement, ask a question.\nUse it when a call refuses what should work, when something the user needs is missing, or\nwhen the user asks you to tell us something. We read every message, and early feedback shapes\nwhat gets built. The answer comes back in the same thread: read it with `GET\n/support/threads/{id}` and relay it to the user. Threads are shared with the members of the\naccount, and a message written by an integration is signed as such. Sending is capped at ten\nmessages per day per credential.\n", "tags": [ "Support" ], "x-scope": "read", "x-mcp-tool": "contact_support", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "maxLength": 10000, "description": "What you want to tell us. Include what you tried and what happened." }, "subject": { "type": "string", "description": "Title of the thread. Derived from the message when omitted; ignored when replying." }, "kind": { "allOf": [ { "$ref": "#/components/schemas/SupportMessageKind" } ], "description": "Sorts the message on arrival." }, "thread_id": { "type": "string", "format": "uuid", "description": "Reply to this thread instead of opening a new one." } } } } } }, "responses": { "200": { "description": "The message was sent, and the thread it landed in.", "content": { "application/json": { "schema": { "type": "object", "required": [ "sent", "thread_id" ], "properties": { "sent": { "type": "boolean", "const": true }, "thread_id": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/support/threads": { "get": { "operationId": "listSupportThreads", "summary": "List the support threads of the account", "description": "The threads of the account, most recent first.", "tags": [ "Support" ], "x-scope": "read", "x-mcp-tool": "list_support_threads", "responses": { "200": { "description": "The support threads.", "content": { "application/json": { "schema": { "type": "object", "required": [ "threads" ], "properties": { "threads": { "type": "array", "items": { "$ref": "#/components/schemas/SupportThread" } } } } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/support/threads/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the support thread.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getSupportThread", "summary": "Read one thread with its messages", "description": "One thread with its messages, answers of the support team included.", "tags": [ "Support" ], "x-scope": "read", "x-mcp-tool": "get_support_thread", "responses": { "200": { "description": "The thread and its messages.", "content": { "application/json": { "schema": { "type": "object", "required": [ "thread" ], "properties": { "thread": { "$ref": "#/components/schemas/SupportThread" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "The API key of an Epovest account: `Authorization: Bearer epo_...`. The secret starts with\n`epo_` and is shown once, at creation. A revoked key stops working immediately. The scope an\noperation takes is stated under `x-scope`: `read`, which every key has, or `write`. Writing\nalso takes authority inside the account, which an API key always carries, and which the\none-click OAuth connection of the MCP server reads from the person who approved it.\n" } }, "parameters": { "TrackerId": { "name": "id", "in": "path", "required": true, "description": "The id of the tracker.", "schema": { "type": "string", "format": "uuid" } }, "ProjectId": { "name": "id", "in": "path", "required": true, "description": "The id of the project.", "schema": { "type": "string", "format": "uuid" } }, "SurfaceId": { "name": "id", "in": "path", "required": true, "description": "The id of the surface.", "schema": { "type": "string", "format": "uuid" } }, "CorroborationId": { "name": "id", "in": "path", "required": true, "description": "The id of the corroboration.", "schema": { "type": "string", "format": "uuid" } }, "LogbookEntryId": { "name": "id", "in": "path", "required": true, "description": "The id of the logbook entry. Suite moves carry no id.", "schema": { "type": "string", "format": "uuid" } }, "QuestId": { "name": "id", "in": "path", "required": true, "description": "The id of the quest.", "schema": { "type": "string", "format": "uuid" } }, "CompetitorScanId": { "name": "id", "in": "path", "required": true, "description": "The id of the competitor scan.", "schema": { "type": "string", "format": "uuid" } }, "SourceId": { "name": "id", "in": "path", "required": true, "description": "The id of the source on the Atlas.", "schema": { "type": "string", "format": "uuid" } }, "CheckKey": { "name": "key", "in": "path", "required": true, "description": "The key of a check of your own. It derives from the label at birth and then freezes, being\nthe coordinate of the cells already recorded.\n", "schema": { "type": "string", "pattern": "^[a-z0-9_]+$" } }, "Page": { "name": "page", "in": "query", "required": false, "description": "Clamped, not rejected: ask for page 99 of 3 and you get page 3 back, with `pagination.page`\nsaying 3. Stop on `pagination.page >= pagination.pages`.\n", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } }, "responses": { "BadRequest": { "description": "`bad_request`: malformed body or parameter; the message says what.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthenticated": { "description": "`unauthenticated`: missing, unknown or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InsufficientScope": { "description": "`insufficient_scope`: the credential may not do this, either because the key lacks the scope,\nor, on a one-click connection, because the person lacks the role the action needs (manager,\nor owner to start, pause and top up). On that path, read it as \"this person may not do this\"\nand tell them which role the action needs.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "`not_found`: unknown for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "`rate_limited`: 120 requests per minute per credential, sliding window. Retry after\n`Retry-After` seconds.\n", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "The budget of the window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "What is left of it.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "`validation_failed`: invalid tracker configuration; `violations[]` lists field and message.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "violations": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": [ "string", "null" ] }, "message": { "type": "string" } } } } } } ] } } } }, "InsufficientCredits": { "description": "`insufficient_credits`: the balance does not cover one survey. The answer carries\n`cost_per_survey_minor` and `available_minor`, so you can name the shortfall to the person,\nand `top_up_url`, the page where they add credit: hand it to them.\n", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "cost_per_survey_minor": { "type": "integer" }, "available_minor": { "type": "integer" }, "top_up_url": { "type": "string", "format": "uri" } } } ] } } } }, "ServiceUnavailable": { "description": "`service_unavailable`: a backend is unreachable; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "The slug of the refusal, stable enough to branch on without parsing the message." }, "message": { "type": "string", "description": "A human sentence saying what happened." } } }, "Pagination": { "type": "object", "required": [ "page", "per_page", "total", "pages" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "ArchiveState": { "type": "object", "description": "The STATE you want. Omitted, it files away; both moves answer the same when replayed.", "properties": { "archived": { "type": "boolean", "default": true } } }, "Engine": { "type": "string", "description": "The AI assistants the questions are asked to.", "enum": [ "chatgpt", "claude", "gemini", "perplexity", "mistral", "grok" ] }, "SurveyFrequency": { "type": "string", "description": "The pace of the surveys.", "enum": [ "monthly", "weekly", "daily" ] }, "SurveyResolution": { "type": "string", "description": "Repetitions of every question per engine and survey: `hd`=1, `full_hd`=3, `4k`=6, `8k`=9.", "enum": [ "hd", "full_hd", "4k", "8k" ] }, "AnalystType": { "type": "string", "description": "`keyword_presence` and `share_of_voice` are deterministic; `sentiment` and `custom_prompt`\nare AI analysts, billed per analyzed response.\n", "enum": [ "keyword_presence", "share_of_voice", "sentiment", "custom_prompt" ] }, "MentionSentiment": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "TrackerStatus": { "type": "string", "enum": [ "draft", "active", "paused", "retired", "abandoned" ] }, "PauseReason": { "type": [ "string", "null" ], "description": "`manual`: the measurement was stopped on purpose, and it waits for\n`POST /trackers/{id}/start`. `credit_exhausted`: the balance no longer covered a survey when\nit was due, and a top-up resumes the tracker on its own. Null on any status other than paused.\n", "enum": [ "manual", "credit_exhausted", null ] }, "SurveyStatus": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "SurfaceType": { "type": "string", "description": "Derived from the address when a surface is registered: a page whose registrable domain is the\ncanon website is `website`, a known place carries its own kind, and any other host is\n`other`, which carries the generic checklist.\n", "enum": [ "website", "github", "linkedin", "x", "youtube", "wikidata", "directory", "app_store", "other" ] }, "ChecklistScope": { "type": "string", "description": "`language` is one cell per language of the surface, `site` one cell for the whole site.", "enum": [ "language", "site" ] }, "ChecklistItemKind": { "type": "string", "description": "What PERISHES the tick of an item: `canon` when it restates the canon wording, so the tick\nperishes with it; `presence` when the tick holds until someone clears it.\n", "enum": [ "canon", "presence" ] }, "RequestChannel": { "type": "string", "description": "Whether someone can be asked to change the page: `available` (a contact or a process exists),\n`none` (nobody to ask) or `unknown` (not filled in, the default). Three states, because \"no\nchannel\" and \"not filled in\" are two different facts.\n", "enum": [ "available", "none", "unknown" ] }, "MonitoringCadence": { "type": "string", "description": "The cadence of the automatic watching of a corroboration. Each executed check runs the same\npass as the on-demand check and debits the prepaid balance per executed check.\n", "enum": [ "off", "daily", "weekly", "monthly" ] }, "LogbookCategory": { "type": "string", "enum": [ "content", "technical", "translation", "canon", "press", "other" ] }, "QuestStatus": { "type": "string", "description": "A quest opens as `open` and closes as `done` (the move happened) or `dismissed` (the customer\nset it aside); both stay readable as history, and both reopen.\n", "enum": [ "open", "done", "dismissed" ] }, "SupportMessageKind": { "type": "string", "enum": [ "problem", "suggestion", "question" ] }, "CompetitorTemplate": { "type": "string", "description": "Which of the four questions each company gets.", "enum": [ "about_reputation", "about_price", "about_customers", "compared_alternatives" ] }, "PlaceReach": { "type": "string", "description": "The way in: `self_serve` to open your own page, `participate` for a forum or a community,\n`ask` for a third-party editorial site, `registry` when the page follows an official filing.\n", "enum": [ "self_serve", "participate", "ask", "registry" ] }, "SpendCategory": { "type": "string", "description": "The cost line: `survey`, `ai_analyst` (the supplement of the AI analysts grafted onto a\ncheck), `competitor_scan`, `corroboration_check`, and `other` for a line not named yet, which\nstays visible rather than dropping out of a total.\n", "enum": [ "survey", "ai_analyst", "competitor_scan", "corroboration_check", "other" ] }, "EngineAuthority": { "type": "object", "description": "What one AI grants a domain over the last 30 days, 0 to 100, where 100 is the source that AI cites the most.", "required": [ "engine", "aa" ], "properties": { "engine": { "$ref": "#/components/schemas/Engine" }, "aa": { "type": "integer", "minimum": 0, "maximum": 100 } } }, "ProjectRef": { "type": [ "object", "null" ], "description": "The project a tracker is filed under, null for the virtual `Default` project.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "Keyword": { "type": "object", "required": [ "keyword", "favorite" ], "properties": { "keyword": { "type": "string" }, "favorite": { "type": "boolean" } } }, "Tracker": { "type": "object", "required": [ "id", "title", "project", "chain", "version", "status", "engines", "frequency", "resolution", "repetitions", "prompts", "keywords", "analysts", "custom_prompt", "discovery", "notify_on_survey", "cost_per_survey_minor", "monthly_estimate_minor", "currency", "created_at", "activated_at", "next_survey_at", "pause_reason", "archived", "archived_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "project": { "$ref": "#/components/schemas/ProjectRef" }, "chain": { "type": "string", "description": "The name of the chain the versions of this tracker share." }, "version": { "type": "integer" }, "status": { "$ref": "#/components/schemas/TrackerStatus" }, "engines": { "type": "array", "items": { "$ref": "#/components/schemas/Engine" } }, "frequency": { "$ref": "#/components/schemas/SurveyFrequency" }, "resolution": { "$ref": "#/components/schemas/SurveyResolution" }, "repetitions": { "type": "integer", "description": "Repetitions of every question per engine and survey, as the resolution sets them." }, "prompts": { "type": "array", "description": "The questions asked to the engines at every survey.", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/Keyword" } }, "analysts": { "type": "array", "items": { "$ref": "#/components/schemas/AnalystType" } }, "custom_prompt": { "type": [ "string", "null" ] }, "discovery": { "type": "boolean", "description": "Suggests new keywords spotted in the answers. It works from the keywords of the tracker,\nso read it back here rather than assuming it took.\n" }, "notify_on_survey": { "type": "boolean", "description": "Emails the account owner and managers each time a survey closes with fresh data. On by\ndefault.\n" }, "cost_per_survey_minor": { "type": "integer", "description": "Recalculated from the configuration on every read, in minor units of `currency`." }, "monthly_estimate_minor": { "type": "integer" }, "currency": { "type": "string", "description": "The wallet currency of the account." }, "created_at": { "type": "string", "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_survey_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next survey runs. A past instant means within the hour; null when nothing is\nscheduled, which is a paused tracker, or a draft whose first survey runs at start.\n" }, "pause_reason": { "$ref": "#/components/schemas/PauseReason" }, "archived": { "type": "boolean", "description": "The FOLDER, next to the measurement rather than inside it: a filed tracker keeps its\nstatus, and `GET /trackers` lists the ones still followed first.\n" }, "archived_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "TrackerCreate": { "type": "object", "required": [ "title", "prompts", "engines", "frequency", "resolution" ], "properties": { "title": { "type": "string", "description": "Display name." }, "prompts": { "type": "array", "minItems": 1, "description": "The questions asked to the engines at every survey, phrased as a customer would ask them.", "items": { "type": "string" } }, "engines": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Engine" } }, "frequency": { "$ref": "#/components/schemas/SurveyFrequency" }, "resolution": { "$ref": "#/components/schemas/SurveyResolution" }, "keywords": { "type": "array", "description": "Names to detect in the answers, as `\"Name\"` or `{\"keyword\": \"Name\", \"favorite\": true}`.", "items": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/Keyword" } ] } }, "analysts": { "type": "array", "items": { "$ref": "#/components/schemas/AnalystType" } }, "custom_prompt": { "type": "string", "description": "The instruction of the `custom_prompt` analyst; it comes with it." }, "discovery": { "type": "boolean", "description": "Suggests new keywords spotted in the answers. It works from keywords, so send\n`keywords[]` alongside, and check `discovery` in the answer.\n" }, "notify_on_survey": { "type": "boolean", "default": true }, "next_survey_at": { "type": "string", "description": "When the first survey runs, ISO 8601 with a date AND a time (`2026-08-01T09:00`), strictly\nin the future, read as UTC without an offset. Omitted, the first survey runs at start.\n" }, "project_id": { "type": "string", "description": "The UUID of a project of the account, or `default` for none. Omitted, the tracker files under Default." } } }, "TrackerUpdate": { "allOf": [ { "$ref": "#/components/schemas/TrackerCreate" }, { "type": "object", "description": "Every field of the creation, all optional; a sent list replaces the previous one entirely.", "required": [] } ] }, "Survey": { "type": "object", "required": [ "id", "period_start", "status", "panel_version", "on_demand", "requested_at", "started_at", "completed_at", "billed_analysts" ], "properties": { "id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string", "format": "date" }, "status": { "$ref": "#/components/schemas/SurveyStatus" }, "panel_version": { "type": "integer", "description": "The tracker version that ran it, the series spanning versions." }, "on_demand": { "type": "boolean", "description": "True when the survey was asked for on the tracker rather than run by the cadence." }, "requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "billed_analysts": { "type": "array", "description": "The AI analysts reserved on that survey, snapshotted at creation, what the credit hold\ncovered. Empty when none.\n", "items": { "$ref": "#/components/schemas/AnalystType" } } } }, "Score": { "type": "object", "required": [ "analyst", "keyword", "favorite", "engine", "panel_version", "period_start", "on_demand", "citation_rate", "weighted_score", "share_of_voice", "sentiment", "runs_counted", "computed_at" ], "properties": { "analyst": { "$ref": "#/components/schemas/AnalystType" }, "keyword": { "type": "string" }, "favorite": { "type": "boolean" }, "engine": { "$ref": "#/components/schemas/Engine" }, "panel_version": { "type": "integer" }, "period_start": { "type": "string", "format": "date" }, "on_demand": { "type": "boolean" }, "citation_rate": { "type": [ "number", "null" ] }, "weighted_score": { "type": [ "number", "null" ] }, "share_of_voice": { "type": [ "number", "null" ] }, "sentiment": { "type": [ "object", "null" ], "description": "The counts of the sentiment analyst, present on its rows.", "properties": { "positive": { "type": "integer" }, "neutral": { "type": "integer" }, "negative": { "type": "integer" } } }, "runs_counted": { "type": "integer" }, "computed_at": { "type": "string", "format": "date-time" } } }, "ResponseSource": { "type": "object", "required": [ "url", "domain", "position" ], "properties": { "url": { "type": "string" }, "domain": { "type": "string" }, "position": { "type": [ "integer", "null" ] } } }, "ResponseMention": { "type": "object", "required": [ "keyword", "rank", "linked", "sentiment" ], "properties": { "keyword": { "type": "string" }, "rank": { "type": [ "integer", "null" ] }, "linked": { "type": "boolean" }, "sentiment": { "oneOf": [ { "$ref": "#/components/schemas/MentionSentiment" }, { "type": "null" } ] } } }, "EngineResponse": { "type": "object", "required": [ "id", "survey_id", "period_start", "on_demand", "panel_version", "engine", "question", "repetition", "model", "responded_at", "response_text", "searched", "sources", "uncited_sources", "mentions" ], "properties": { "id": { "type": "string", "format": "uuid" }, "survey_id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string", "format": "date" }, "on_demand": { "type": "boolean" }, "panel_version": { "type": "integer" }, "engine": { "$ref": "#/components/schemas/Engine" }, "question": { "type": "string" }, "repetition": { "type": "integer" }, "model": { "type": [ "string", "null" ] }, "responded_at": { "type": [ "string", "null" ], "format": "date-time" }, "response_text": { "type": [ "string", "null" ] }, "searched": { "type": [ "boolean", "null" ], "description": "Whether the engine went to the web to write the answer. Null when undetermined, for\nanswers measured before the field existed.\n" }, "sources": { "type": "array", "description": "The pages the engine cited.", "items": { "$ref": "#/components/schemas/ResponseSource" } }, "uncited_sources": { "type": "array", "description": "The pages the engine read to write the answer without citing them.", "items": { "$ref": "#/components/schemas/ResponseSource" } }, "mentions": { "type": "array", "items": { "$ref": "#/components/schemas/ResponseMention" } }, "raw_response": { "description": "The full engine payload. Present when `include=raw` was asked for." } } }, "KeywordDiscovery": { "type": "object", "required": [ "domain", "sources", "keyword" ], "properties": { "domain": { "type": "string" }, "sources": { "type": "integer", "description": "How many times that domain appeared, recomputed on every read." }, "keyword": { "type": "string", "description": "The name the domain would be tracked under." } } }, "DomainOrDomains": { "type": "object", "description": "Send `domain` for one, or `domains` for several, never both. A batch is all or nothing, so\nyou never have to guess which half took. The answer echoes the shape you sent.\n", "properties": { "domain": { "type": "string" }, "domains": { "type": "array", "minItems": 1, "items": { "type": "string" } } }, "oneOf": [ { "required": [ "domain" ] }, { "required": [ "domains" ] } ] }, "Canon": { "type": "object", "description": "The brand identity sheet: the text every publication reuses as is, so all mentions tell the\nsame entity. It lives in ONE language per project, its canonical language, and the facts are\nlanguage-NEUTRAL and identical everywhere.\n", "required": [ "one_liner", "short", "long", "category", "language", "perks", "website", "legal_name", "address", "phone", "whatsapp", "email" ], "properties": { "one_liner": { "type": [ "string", "null" ] }, "short": { "type": [ "string", "null" ] }, "long": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ], "description": "The canonical language, a short code like `en` or `pt-br`. Null when never declared." }, "perks": { "type": "array", "description": "The ordered list of distinctive claims, written in the canonical language, meant to be\nhammered so the engines bring them up on their own: facts that hold and can be\ncorroborated.\n", "items": { "type": "string" } }, "website": { "type": [ "string", "null" ], "description": "The canonical address that identifies the entity, ONE URL only. A bare domain completes\nto https, and a trailing slash is dropped.\n" }, "legal_name": { "type": [ "string", "null" ], "description": "The registered name of the company that operates the brand, with its jurisdiction when it\nis stated: the name the AIs cross-read to anchor the entity.\n" }, "address": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "whatsapp": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "CanonFields": { "type": "object", "description": "The canon, field by field. A sent field replaces the current wording, an empty string or\n`null` clears it, and an omitted field is kept as is.\n", "properties": { "canon_one_liner": { "type": [ "string", "null" ] }, "canon_short": { "type": [ "string", "null" ] }, "canon_long": { "type": [ "string", "null" ] }, "canon_category": { "type": [ "string", "null" ] }, "canon_language": { "type": [ "string", "null" ] }, "canon_perks": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "canon_website": { "type": [ "string", "null" ] }, "canon_legal_name": { "type": [ "string", "null" ] }, "canon_address": { "type": [ "string", "null" ] }, "canon_phone": { "type": [ "string", "null" ] }, "canon_whatsapp": { "type": [ "string", "null" ] }, "canon_email": { "type": [ "string", "null" ] } } }, "CanonVersion": { "type": "object", "required": [ "version", "author", "created_at", "initial", "changes" ], "properties": { "version": { "type": "integer" }, "author": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "initial": { "type": "boolean", "description": "True on version 1, which has nothing before it." }, "changes": { "type": "array", "description": "One entry per field that version touched, with the raw values: `perks` comes back as its\nordered list and `language` as its short code. `before` is the wording the version\nreplaced, which is the string to find on a page that still carries it.\n", "items": { "type": "object", "required": [ "field", "before", "after" ], "properties": { "field": { "type": "string" }, "before": [], "after": [] } } } } }, "Project": { "type": "object", "required": [ "id", "name", "canon", "canon_version", "link_targets", "archived", "tracker_count", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "canon": { "$ref": "#/components/schemas/Canon" }, "canon_version": { "type": [ "integer", "null" ] }, "link_targets": { "type": "array", "description": "The free addresses of the brand set on the project, the ones read by `GET /projects/{id}/link-targets`.", "items": { "type": "string" } }, "archived": { "type": "boolean" }, "tracker_count": { "type": "integer", "description": "How many trackers are still filed under it." }, "created_at": { "type": "string", "format": "date-time" } } }, "ProjectEnvelope": { "type": "object", "required": [ "project" ], "properties": { "project": { "$ref": "#/components/schemas/Project" } } }, "LinkTargets": { "type": "object", "required": [ "derived", "free" ], "properties": { "derived": { "type": "array", "description": "What is already covered from work done elsewhere.", "items": { "type": "object", "required": [ "url", "source" ], "properties": { "url": { "type": "string" }, "source": { "type": "string", "enum": [ "canon", "surface" ] } } } }, "free": { "type": "array", "description": "What has been set on the project on top of the derived ones.", "items": { "type": "string" } } } }, "ChecklistCell": { "type": "object", "description": "A verified cell carries `{state, canon_version, fresh, at, by}`, a set-aside one\n`{state, reason, at, by}`.\n", "properties": { "state": { "type": "string", "enum": [ "verified", "dismissed" ] }, "canon_version": { "type": [ "integer", "null" ], "description": "The canon version whose wording the verification restated." }, "fresh": { "type": "boolean", "description": "Whether the verification still holds at the current wording." }, "reason": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "by": { "type": [ "string", "null" ] } } }, "CustomCheck": { "type": "object", "required": [ "key", "label", "scope", "restates_canon", "deleted", "deleted_at", "created_at" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "scope": { "$ref": "#/components/schemas/ChecklistScope" }, "restates_canon": { "type": "boolean" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Checklist": { "type": "object", "required": [ "items", "site_items", "kinds", "required", "custom", "state", "cells", "progress" ], "properties": { "items": { "type": "array", "description": "The template of the type, with stable keys such as `title_tag` or `llms_txt`, followed by the checks the customer added of their own.", "items": { "type": "string" } }, "site_items": { "type": "array", "description": "The items that are site-wide, one cell for the whole site, under the `site` column.", "items": { "type": "string" } }, "kinds": { "type": "object", "description": "The kind of each item.", "additionalProperties": { "$ref": "#/components/schemas/ChecklistItemKind" } }, "required": { "type": "array", "description": "What HOLDS the status: the canon items of the template plus every check of the customer,\nwhatever its kind. Read this list rather than deducing from `kinds`.\n", "items": { "type": "string" } }, "custom": { "type": "array", "description": "The definitions of the checks of the customer, the ones taken out included.", "items": { "$ref": "#/components/schemas/CustomCheck" } }, "state": { "type": "object", "description": "The flat view of the verified items, per column.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "cells": { "type": "object", "description": "The detail of each cell, per column then per item.", "additionalProperties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChecklistCell" } } }, "progress": { "type": "object", "description": "What holds at the current wording, over the cells that are not set aside, with the\nset-aside ones counted apart.\n", "required": [ "done", "total", "dismissed" ], "properties": { "done": { "type": "integer" }, "total": { "type": "integer" }, "dismissed": { "type": "integer" } } } } }, "DomainAuthority": { "type": "object", "description": "The join with the Atlas: what the AIs grant the DOMAIN the page sits on. An AI absent from\n`engines` has not cited the domain lately, and a `source_id` of null says the domain is not\non the map of this account, which grows as you measure more.\n", "required": [ "domain", "source_id", "engines", "last_detected_on" ], "properties": { "domain": { "type": "string", "description": "The registrable domain read from the address by the same normalisation as the map." }, "source_id": { "type": [ "string", "null" ], "format": "uuid" }, "engines": { "type": "array", "items": { "$ref": "#/components/schemas/EngineAuthority" } }, "last_detected_on": { "type": [ "string", "null" ], "format": "date" } } }, "Surface": { "type": "object", "required": [ "id", "project_id", "type", "url", "label", "languages", "notes", "status", "alignment", "checklist", "domain_authority", "deleted", "deleted_at", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/SurfaceType" }, "url": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "languages": { "type": "array", "description": "Short language codes. They ARE the columns of the checklist.", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "Derived on read from the checklist cells that hold it, the ones listed in\n`checklist.required`: `aligned` (every required cell not set aside is verified at the\ncurrent wording), `needs_update` (a verification is missing or stale), `never_aligned`\n(none exists yet).\n", "enum": [ "aligned", "needs_update", "never_aligned" ] }, "alignment": { "type": [ "object", "null" ], "description": "The last journal line.", "properties": { "canon_version": { "type": "integer" }, "aligned_at": { "type": "string", "format": "date-time" }, "author": { "type": [ "string", "null" ] } } }, "checklist": { "$ref": "#/components/schemas/Checklist" }, "domain_authority": { "$ref": "#/components/schemas/DomainAuthority" }, "deleted": { "type": "boolean" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "SurfaceEnvelope": { "type": "object", "required": [ "surface" ], "properties": { "surface": { "$ref": "#/components/schemas/Surface" } } }, "SurfaceCheckEnvelope": { "type": "object", "required": [ "surface", "check" ], "properties": { "surface": { "$ref": "#/components/schemas/Surface" }, "check": { "type": "string", "description": "The key of the check, which freezes at birth." } } }, "DroppedChecklistColumn": { "type": "object", "description": "A column that left the model after a sheet edit. Its cells stay stored, so declaring that\nlanguage again brings them back.\n", "required": [ "language", "verified", "dismissed" ], "properties": { "language": { "type": "string" }, "verified": { "type": "integer" }, "dismissed": { "type": "integer" } } }, "ChecklistTick": { "type": "object", "required": [ "item" ], "properties": { "item": { "type": "string", "description": "One of `checklist.items`, the template of the type plus the checks of the customer." }, "language": { "type": [ "string", "null" ], "description": "One of the columns of `checklist.state`. A site-wide item is one cell for the whole site,\nso it goes without a language, and a surface with a single column can leave it out.\n" }, "done": { "type": [ "boolean", "null" ], "description": "True or omitted verifies the item; false clears the cell." }, "dismissed": { "type": [ "boolean", "null" ], "description": "True sets the item aside, with a `reason` due; false brings it back." }, "reason": { "type": [ "string", "null" ], "description": "The short wording of why the item does not apply on this surface." } } }, "LinkSighting": { "type": "object", "description": "One link of the page towards an address of the brand.", "properties": { "url": { "type": "string" }, "kind": { "type": [ "string", "null" ] }, "anchor": { "type": [ "string", "null" ] }, "rel": { "type": "array", "description": "The rel tokens of the link, among `nofollow`, `sponsored` and `ugc`.", "items": { "type": "string" } }, "html_target": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "in_main_content": { "type": [ "boolean", "null" ] }, "nature": { "type": [ "string", "null" ] }, "final_url": { "type": [ "string", "null" ] }, "hops": { "type": [ "integer", "null" ] }, "final_status": { "type": [ "integer", "null" ] }, "first_seen": { "type": "string", "format": "date-time" }, "last_seen": { "type": "string", "format": "date-time" }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "PageCheck": { "type": "object", "description": "The latest reading of the page, refreshed by `POST /corroborations/{id}/verify` and by the watching cadence.", "required": [ "readability", "checked_at", "http_status", "mention", "link" ], "properties": { "readability": { "type": "string", "enum": [ "pending", "html", "unreadable", "blocked", "unreachable", "no_page" ] }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "http_status": { "type": [ "integer", "null" ] }, "mention": { "type": "object", "description": "The finding on the passage around the brand: `unchanged`, `changed` (the passage moved,\nworth re-reading), `figures` (it moved on NUMBERS only, such as a rank or a counter, so\n`changed_at` stays where it was) or `gone` (the page did not answer).\n", "properties": { "finding": { "type": [ "string", "null" ], "enum": [ "unchanged", "changed", "figures", "gone", null ] }, "excerpt": { "type": [ "string", "null" ] }, "excerpt_before": { "type": [ "string", "null" ], "description": "The passage as it stood BEFORE `changed_at`, so comparing the two texts says what\nmoved without reading the whole page again.\n" }, "extractor": { "type": [ "string", "null" ] }, "changed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "link": { "type": [ "object", "null" ], "description": "The finding on the links of the page towards the addresses of the brand.", "properties": { "finding": { "type": "string", "enum": [ "unchanged", "changed", "gone", "none" ] }, "changes": { "type": "array", "items": [] }, "outbound": { "type": [ "integer", "null" ] }, "noindex": { "type": [ "boolean", "null" ] }, "page_nofollow": { "type": [ "boolean", "null" ] }, "canonical_elsewhere": { "type": [ "string", "null" ] }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/LinkSighting" } } } } } }, "Corroboration": { "type": "object", "required": [ "id", "project_id", "url", "domain", "label", "notes", "published_on", "author", "request_channel", "monitoring", "monitoring_paused", "archived", "page_check", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "description": "The exact page." }, "domain": { "type": "string", "description": "The registrable domain the page sits on, derived from the address by the same normalizer\nas the Atlas. Correcting the `url` always recomputes it.\n" }, "label": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "published_on": { "type": [ "string", "null" ], "format": "date", "description": "The day the page was PUBLISHED, distinct from `created_at`, the day it was recorded. It is\nthe publication date that means something against the citation curves.\n" }, "author": { "type": [ "string", "null" ] }, "request_channel": { "$ref": "#/components/schemas/RequestChannel" }, "monitoring": { "$ref": "#/components/schemas/MonitoringCadence" }, "monitoring_paused": { "type": "boolean", "description": "True while the passes wait on the balance, the cadence kept: a top-up resumes them as they\nwere.\n" }, "archived": { "type": "boolean" }, "page_check": { "$ref": "#/components/schemas/PageCheck" }, "created_at": { "type": "string", "format": "date-time" } } }, "CorroborationEnvelope": { "type": "object", "required": [ "corroboration" ], "properties": { "corroboration": { "$ref": "#/components/schemas/Corroboration" } } }, "CorroborationCandidate": { "type": "object", "required": [ "url", "domain", "excerpt", "matched_by", "engines", "seen_on", "published_on", "suggested" ], "properties": { "url": { "type": "string" }, "domain": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "matched_by": { "type": "string", "description": "The strength of the proof: `website` means the full domain of the brand appears in the\nexcerpt, which is near proof; `name` means only the name did, so read the page before\nrecording it.\n", "enum": [ "website", "name" ] }, "engines": { "type": "array", "items": { "$ref": "#/components/schemas/Engine" } }, "seen_on": { "type": "string", "format": "date" }, "published_on": { "type": [ "string", "null" ], "format": "date" }, "suggested": { "type": "string", "description": "The registry the filing is proposed in: `surface` when the host is a known profile place,\n`ask` when the address looks like a listing on a place outside that catalogue, so it can\nbe either side, and `corroboration` otherwise. On an `ask`, the test that settles it is\nthe criterion itself: if they change that page, does the change stay?\n", "enum": [ "surface", "ask", "corroboration" ] }, "page_check": { "type": "object", "description": "Present when the page was read.", "properties": { "result": { "type": [ "string", "null" ] }, "excerpt": { "type": [ "string", "null" ] }, "checked_at": { "type": "string", "format": "date-time" } } } } }, "LogbookItem": { "type": "object", "description": "One move of the timeline. `source` says where it comes from and `kind` what it is; the keys\nbelow the first four depend on the kind.\n", "required": [ "source", "kind", "occurred_at", "author" ], "properties": { "source": { "type": "string", "enum": [ "tool", "manual" ] }, "kind": { "type": "string", "enum": [ "canon_version", "surface_aligned", "corroboration", "corroboration_archived", "entry" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "The date of the action. On a `corroboration` item it is the PUBLICATION date when it is\nknown, and the recording date otherwise, `published_on` sitting right next to it so you\ncan tell which one you are reading.\n" }, "author": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid", "description": "Manual entries only." }, "category": { "$ref": "#/components/schemas/LogbookCategory" }, "label": { "type": "string", "description": "Manual entries only." }, "notes": { "type": [ "string", "null" ] }, "recorded_at": { "type": "string", "format": "date-time", "description": "The day the entry was recorded." }, "quest_id": { "type": [ "string", "null" ], "format": "uuid" }, "quest": { "type": [ "string", "null" ], "description": "The title of the quest the action moves forward." }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The day the entry left the logbook." }, "canon_version": { "type": [ "integer", "null" ] }, "changed": { "type": "array", "description": "The canon keys that revision touched: the number says the registry has work waiting,\n`changed` says what the work is about. Version 1 lists everything it posted.\n", "items": { "type": "string" } }, "surface_id": { "type": "string", "format": "uuid" }, "surface": { "type": "string" }, "corroboration_id": { "type": "string", "format": "uuid" }, "corroboration": { "type": "string" }, "url": { "type": "string" }, "domain": { "type": "string" }, "published_on": { "type": [ "string", "null" ], "format": "date" }, "archived": { "type": "boolean" } } }, "LogbookEntryEnvelope": { "type": "object", "required": [ "entry" ], "properties": { "entry": { "$ref": "#/components/schemas/LogbookItem" }, "restored": { "type": "boolean", "description": "Present on a creation whose twin was an entry that had been taken out: it came back\nrather than being written a second time.\n" } } }, "Quest": { "type": "object", "required": [ "id", "project_id", "project", "title", "notes", "status", "author", "created_at", "closed_at", "journal_entries", "last_entry_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "project": { "type": "string", "description": "The name of the project." }, "title": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/QuestStatus" }, "author": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "journal_entries": { "type": "integer", "description": "How many actions were recorded against this quest." }, "last_entry_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "QuestEnvelope": { "type": "object", "required": [ "quest" ], "properties": { "quest": { "$ref": "#/components/schemas/Quest" } } }, "QuestPending": { "type": "object", "description": "The work the measurement itself is holding for review, composed on every read from the\nproduct's own registries, so it empties on its own as the moves are made.\n", "required": [ "surfaces_to_align", "corroborations_to_refresh", "corroborations_to_reread", "keyword_discoveries" ], "properties": { "surfaces_to_align": { "type": "array", "description": "The surfaces whose canon moved since they were last marked aligned.", "items": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid" }, "project": { "type": "string" }, "surface_id": { "type": "string", "format": "uuid" }, "surface": { "type": "string" }, "url": { "type": "string" } } } }, "corroborations_to_refresh": { "type": "array", "description": "The corroborations recorded or published BEFORE the current canon version whose request\nchannel is not `none`, oldest first. A suggested move, never a status.\n", "items": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid" }, "project": { "type": "string" }, "corroboration_id": { "type": "string", "format": "uuid" }, "corroboration": { "type": "string" }, "url": { "type": "string" }, "published_on": { "type": [ "string", "null" ], "format": "date" }, "request_channel": { "$ref": "#/components/schemas/RequestChannel" } } } }, "corroborations_to_reread": { "type": "array", "description": "The lines whose last reading found the text moved, the link gone, or the page silent.", "items": { "type": "object", "properties": { "project_id": { "type": "string", "format": "uuid" }, "project": { "type": "string" }, "corroboration_id": { "type": "string", "format": "uuid" }, "corroboration": { "type": "string" }, "url": { "type": "string" }, "mention_finding": { "type": [ "string", "null" ] }, "link_finding": { "type": [ "string", "null" ] }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" } } } }, "keyword_discoveries": { "type": "array", "description": "The trackers with suggestions waiting; read them with `GET /trackers/{id}/discoveries`.", "items": { "type": "object", "properties": { "tracker_id": { "type": "string", "format": "uuid" }, "tracker": { "type": "string" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "project": { "type": [ "string", "null" ] }, "count": { "type": "integer" } } } }, "corroboration_candidates": { "type": "array", "description": "The same entries as `GET /projects/{id}/corroboration-candidates`. They are computed per\nproject, so the key comes with the project-scoped read.\n", "items": { "$ref": "#/components/schemas/CorroborationCandidate" } } } }, "CompetitorScan": { "type": "object", "required": [ "id", "project_id", "project", "title", "engine", "language", "country", "category", "usage", "status", "rescan_cadence", "checks_completed", "estimated_cost_minor", "subjects", "questions", "created_at", "launched_at", "author" ], "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "project": { "type": "string" }, "title": { "type": "string" }, "engine": { "$ref": "#/components/schemas/Engine" }, "language": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "usage": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "measuring", "ready", "failed" ] }, "rescan_cadence": { "type": [ "string", "null" ], "enum": [ "weekly", "monthly", null ] }, "checks_completed": { "type": "integer" }, "estimated_cost_minor": { "type": "integer", "description": "What arming the scan spends, in minor units of the wallet currency." }, "subjects": { "type": "array", "maxItems": 5, "items": { "type": "object", "properties": { "name": { "type": "string" }, "website": { "type": "string" }, "domain": { "type": "string" } } } }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": "string" }, "family": { "type": "string", "enum": [ "about", "compared" ] }, "template": { "$ref": "#/components/schemas/CompetitorTemplate" }, "text": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "launched_at": { "type": [ "string", "null" ], "format": "date-time" }, "author": { "type": [ "string", "null" ] } } }, "CompetitorScanEnvelope": { "type": "object", "required": [ "competitor_scan" ], "properties": { "competitor_scan": { "$ref": "#/components/schemas/CompetitorScan" } } }, "CompetitorPlacePage": { "type": "object", "properties": { "url": { "type": "string" }, "cited": { "type": "integer" }, "read": { "type": "integer" }, "best_position": { "type": [ "integer", "null" ] }, "seen_in_checks": { "type": "integer" }, "first_seen_on": { "type": [ "string", "null" ], "format": "date" }, "last_seen_on": { "type": [ "string", "null" ], "format": "date" } } }, "CompetitorScanReport": { "type": "object", "required": [ "checks", "measured_from", "measured_to", "answers_collected", "answers_with_sources", "places", "controlled", "rivals" ], "properties": { "checks": { "type": "integer" }, "measured_from": { "type": [ "string", "null" ], "format": "date" }, "measured_to": { "type": [ "string", "null" ], "format": "date" }, "answers_collected": { "type": "integer" }, "answers_with_sources": { "type": "integer" }, "places": { "type": "array", "description": "The domains the engine cited while answering about the basket, ranked by how many of it each place covers.", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "reach": { "$ref": "#/components/schemas/PlaceReach" }, "subjects": { "type": "integer", "description": "How many of the basket are corroborated there." }, "subject_names": { "type": "array", "items": { "type": "string" } }, "ai_authority": { "type": [ "integer", "null" ] }, "source_id": { "type": [ "string", "null" ], "format": "uuid" }, "citations": { "type": "integer" }, "reads": { "type": "integer" }, "best_position": { "type": [ "integer", "null" ] }, "seen_in_checks": { "type": "integer", "description": "How many checks brought the place back. The list accumulates over every check, deduplicated by URL." }, "first_seen_on": { "type": [ "string", "null" ], "format": "date" }, "last_seen_on": { "type": [ "string", "null" ], "format": "date" }, "client_present": { "type": "boolean", "description": "Whether the account already recorded a corroboration there." }, "client_owned": { "type": "boolean" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorPlacePage" } } } } }, "controlled": { "type": "array", "description": "What each company publishes on its own site.", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "domain": { "type": "string" }, "page_count": { "type": "integer" }, "citations": { "type": "integer" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorPlacePage" } } } } }, "rivals": { "type": "array", "description": "The competitive set the engine names.", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "subjects": { "type": "integer" }, "subject_names": { "type": "array", "items": { "type": "string" } } } } } } }, "Source": { "type": "object", "required": [ "id", "domain", "engines", "last_detected_on" ], "properties": { "id": { "type": "string", "format": "uuid" }, "domain": { "type": "string", "description": "The registrable domain, so a hosting platform counts as one source rather than one per author." }, "engines": { "type": "array", "description": "Which engines cite this source, and what it weighs on each.", "items": { "$ref": "#/components/schemas/EngineAuthority" } }, "last_detected_on": { "type": "string", "format": "date" } } }, "SourceChannels": { "type": "object", "required": [ "source", "channels", "videos", "named", "unnamed", "pending", "citations" ], "properties": { "source": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain": { "type": "string" } } }, "channels": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "questions": { "type": "integer", "description": "How many of your questions the channel came back on. It is what orders the list." }, "videos": { "type": "integer" }, "citations": { "type": "integer" }, "surveys": { "type": "integer" }, "first_seen_on": { "type": "string", "format": "date" }, "last_seen_on": { "type": "string", "format": "date" }, "you_are_there": { "type": "boolean", "description": "Read from the corroborations this account recorded on that channel or on one of its videos." }, "video_list": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "questions": { "type": "array", "description": "The text of your own questions that surfaced this video.", "items": { "type": "string" } }, "citations": { "type": "integer" }, "surveys": { "type": "integer" }, "first_seen_on": { "type": "string", "format": "date" }, "last_seen_on": { "type": "string", "format": "date" } } } } } } }, "videos": { "type": "integer", "description": "The distinct videos cited on your questions, which is what the list is drawn from." }, "named": { "type": "integer", "description": "Those whose channel is established." }, "unnamed": { "type": "integer", "description": "Those the world does not name." }, "pending": { "type": "integer", "description": "Those still to be established." }, "citations": { "type": "integer" } } }, "Account": { "type": "object", "required": [ "name", "billing_country", "billing_address", "intra_eu_vat_number", "language", "timezone", "member", "created_at" ], "properties": { "name": { "type": [ "string", "null" ], "description": "The legal name of the account, the one printed on its invoices." }, "billing_country": { "type": [ "string", "null" ], "description": "An ISO 3166-1 alpha-2 code. It decides the tax treatment of the next invoices, so it is\nthe country of the entity being billed.\n" }, "billing_address": { "type": "array", "description": "The postal address, one string per line.", "items": { "type": "string" } }, "intra_eu_vat_number": { "type": [ "string", "null" ] }, "language": { "type": "string", "description": "The language we write to this account in, for emails and for the hosted payment page of a top-up.", "enum": [ "en", "fr", "es", "de", "it", "pt" ] }, "timezone": { "type": "string", "description": "The time zone the hours of the account are shown in, as an IANA identifier." }, "member": { "type": [ "object", "null" ], "description": "Who the language and the time zone belong to: the person a one-click connection acts for,\nor the oldest active owner of the account.\n", "properties": { "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "manager", "operator" ] } } }, "created_at": { "type": "string", "format": "date-time" } } }, "Credits": { "type": "object", "required": [ "currency", "balance_minor", "available_minor", "held_minor", "holds", "expires_at", "min_topup_minor", "monthly_estimate_minor", "suggested_topups" ], "properties": { "currency": { "type": "string", "description": "The wallet currency of the account." }, "balance_minor": { "type": "integer", "description": "The gross balance." }, "available_minor": { "type": "integer", "description": "What the account can spend now, net of reservations." }, "held_minor": { "type": "integer" }, "holds": { "type": "array", "description": "Credits reserved by surveys in progress. A reservation is captured when its survey\ncompletes, or released.\n", "items": { "type": "object", "properties": { "amount_minor": { "type": "integer" }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "expires_at": { "type": "null", "description": "Always null: Epovest credits never expire. Kept so an integration that reads it goes on reading it." }, "min_topup_minor": { "type": "integer", "description": "The floor a top-up has to clear." }, "monthly_estimate_minor": { "type": "integer", "description": "What the account has set up to consume in a month: its trackers in draft, running or out\nof credit, plus the corroborations it monitors. `0` when nothing is set up yet.\n" }, "suggested_topups": { "type": "array", "description": "Three amounts derived from that pace, worth one, three and six months of it, rounded and\nnever under the floor. Take one of these when the person leaves the amount to you.\n", "items": { "type": "object", "properties": { "amount_minor": { "type": "integer" }, "amount": { "type": "string", "description": "The same amount in major units." }, "covers_months": { "type": "integer", "description": "The runway it buys." } } } } } }, "SpendLine": { "type": "object", "properties": { "category": { "$ref": "#/components/schemas/SpendCategory" }, "amount_minor": { "type": "integer" }, "count": { "type": "integer" } } }, "ProjectSpend": { "type": "object", "properties": { "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null for the trackers filed under no project." }, "name": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "spent_minor": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SpendLine" } } } }, "TrackerSpend": { "type": "object", "properties": { "tracker_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The current version of the chain, so it goes straight into `GET /trackers/{id}/scores`." }, "name": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "listed": { "type": "boolean", "description": "False for a tracker that is no longer in the account list; its spend still counts in the total." }, "spent_minor": { "type": "integer" }, "survey_count": { "type": "integer" } } }, "Usage": { "type": "object", "required": [ "currency", "month", "period", "this_month_forecast", "total_spent_minor", "by_category", "by_project", "by_tracker", "by_month", "months_total", "entries", "pagination" ], "properties": { "currency": { "type": "string" }, "month": { "type": [ "string", "null" ], "description": "The month asked for, as `YYYY-MM`." }, "period": { "type": "object", "description": "The first and last check debit counted, so quote it alongside the amount.", "properties": { "from": { "type": [ "string", "null" ], "format": "date" }, "to": { "type": [ "string", "null" ], "format": "date" } } }, "this_month_forecast": { "type": "object", "description": "The month in progress: `total_minor` is `spent_minor` (already debited) plus\n`remaining_minor` (what the active trackers and monitored corroborations will still run\nbefore month end, counted as real occurrences and recomputed from their configuration).\nA forecast: report it as one.\n", "properties": { "month": { "type": "string" }, "total_minor": { "type": "integer" }, "spent_minor": { "type": "integer" }, "remaining_minor": { "type": "integer" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/SpendLine" } }, "active_trackers": { "type": "integer" }, "monitored_corroborations": { "type": "integer" } } }, "total_spent_minor": { "type": "integer", "description": "The check spend of the period, matching the sum of both breakdowns." }, "by_category": { "type": "array", "items": { "$ref": "#/components/schemas/SpendLine" } }, "by_project": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSpend" } }, "by_tracker": { "type": "array", "description": "The spend of each tracker over the period, biggest spender first.", "items": { "$ref": "#/components/schemas/TrackerSpend" } }, "by_month": { "type": "array", "description": "Per month, newest first, up to twelve.", "items": { "type": "object", "properties": { "month": { "type": "string" }, "spent_minor": { "type": "integer" }, "by_category": { "type": "array", "items": { "$ref": "#/components/schemas/SpendLine" } }, "by_project": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSpend" } }, "by_tracker": { "type": "array", "items": { "$ref": "#/components/schemas/TrackerSpend" } } } } }, "months_total": { "type": "integer", "description": "How many months have spend, so you can tell whether twelve covered everything." }, "entries": { "type": "array", "description": "The ledger itself, newest first.", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "category": { "oneOf": [ { "$ref": "#/components/schemas/SpendCategory" }, { "type": "null" } ] }, "amount_minor": { "type": "integer", "description": "Signed." }, "balance_after_minor": { "type": [ "integer", "null" ] }, "reason": { "type": [ "string", "null" ] }, "tracker_name": { "type": [ "string", "null" ] }, "period_start": { "type": [ "string", "null" ], "format": "date" }, "on_demand": { "type": [ "boolean", "null" ], "description": "Where a check debit came from: true when the check was asked for on the tracker,\nfalse when the cadence ran it, null on an entry that is not a check debit. The two\nare worth separating in a spend report: one is a decision, the other the schedule.\n" }, "invoice_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "The instant the entry was posted, in RFC 3339 with the UTC offset, to the second and\ncarrying the fraction the ledger recorded: it is the time that tells entries apart\nand orders them.\n" } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "SupportThread": { "type": "object", "description": "A thread of the account with the support team. Threads are shared with the members of the\naccount, who see them in the app.\n", "properties": { "id": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "messages": { "type": "array", "description": "The messages of the thread, in chronological order, answers of the support team included.", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true } } } }