{ "openapi": "3.1.0", "info": { "title": "Cyte API", "description": "Competitor intelligence for online presence: projects, prompts, competitors, runs, suggested improvements, competitor changes, topics and teardowns.", "version": "1.0.0", "contact": { "email": "hello@cyte.si" } }, "servers": [ { "url": "https://app.cyte.si/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from Settings > API Keys in the Cyte dashboard. Requires Advanced plan or above." } } }, "paths": { "/projects": { "get": { "operationId": "listProjects", "summary": "List all projects in the workspace", "description": "Returns all projects (brands) being monitored for AI visibility.", "responses": { "200": { "description": "List of projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Brand name" }, "domain": { "type": "string", "description": "Brand website domain" }, "industry": { "type": "string" }, "lastRunAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "post": { "operationId": "createProject", "summary": "Create a new project", "description": "Creates a new brand/project to monitor for AI visibility.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "domain", "industry" ], "properties": { "name": { "type": "string", "description": "Brand name, e.g. 'Acme Inc'" }, "domain": { "type": "string", "description": "Brand website domain, e.g. 'acme.com'" }, "industry": { "type": "string", "description": "Industry category, e.g. 'SaaS / Software'" } } } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "industry": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/projects/{id}": { "get": { "operationId": "getProject", "summary": "Get project details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Project details including active LLMs and market configuration" } } } }, "/projects/{id}/prompts": { "get": { "operationId": "listPrompts", "summary": "List tracked prompts for a project", "description": "Returns all prompts (search queries) being monitored. These are the questions users ask AI models, e.g. 'best CRM for startups'.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from previous response" } ], "responses": { "200": { "description": "List of prompts with pagination", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string", "description": "The prompt/query being tracked" }, "status": { "type": "string" }, "orderIndex": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "cursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" } } } } } } } }, "post": { "operationId": "createPrompt", "summary": "Add a prompt to track", "description": "Adds a new search query/prompt to monitor across AI models for this project.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "The prompt/query to track, e.g. 'best CRM for startups'" } } } } } }, "responses": { "201": { "description": "Prompt created", "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } } }, "delete": { "operationId": "deletePrompt", "summary": "Delete a tracked prompt", "description": "Removes a prompt from the project. Future runs will no longer include this prompt.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project ID" }, { "name": "promptId", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Prompt deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } } } } }, "/projects/{id}/competitors": { "get": { "operationId": "listCompetitors", "summary": "List competitors being tracked", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of competitors with their domains" } } }, "post": { "operationId": "addCompetitor", "summary": "Add a competitor to track", "description": "Adds a competitor brand to compare visibility against in analysis runs.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "domain" ], "properties": { "name": { "type": "string", "description": "Competitor brand name" }, "domain": { "type": "string", "description": "Competitor website domain" } } } } } }, "responses": { "201": { "description": "Competitor added", "content": { "application/json": { "schema": { "type": "object", "properties": { "competitor": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/projects/{id}/gaps": { "get": { "operationId": "listContentGaps", "summary": "List content gaps where competitors outrank you", "description": "Returns prompts where your brand scores lower than competitors, ranked by priority. Each gap includes the prompt text, your score, the top competitor's score, affected LLMs, and gap type (absent, losing, declining, new_opportunity).", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of content gaps sorted by priority score", "content": { "application/json": { "schema": { "type": "object", "properties": { "gaps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "promptText": { "type": "string" }, "gapType": { "type": "string", "enum": [ "absent", "losing", "declining", "new_opportunity" ] }, "brandScore": { "type": "integer", "description": "Your brand's score (0-100)" }, "topCompetitorName": { "type": "string", "nullable": true }, "topCompetitorScore": { "type": "integer", "nullable": true }, "affectedLlms": { "type": "array", "items": { "type": "string" } }, "priorityScore": { "type": "integer", "description": "Gap priority (higher = more urgent)" }, "status": { "type": "string", "enum": [ "open", "closed" ] } } } } } } } } } } } }, "/projects/{id}/runs": { "get": { "operationId": "listRuns", "summary": "List analysis runs", "description": "Returns history of analysis runs \u2014 each run queries all active LLMs with all tracked prompts and scores the results.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of runs with status and prompt counts" } } }, "post": { "operationId": "triggerRun", "summary": "Trigger a new analysis run", "description": "Starts a new analysis run that queries all active LLMs with all tracked prompts and scores the results. Returns the run ID for polling status.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "description": "ID of the started run" }, "total": { "type": "integer", "description": "Total number of prompt-LLM combinations to process" }, "status": { "type": "string", "enum": [ "running", "queued" ] } } } } } } } } }, "/projects/{id}/runs/{runId}": { "get": { "operationId": "getRunDetails", "summary": "Get detailed results for a specific run", "description": "Returns per-prompt, per-LLM results for a specific analysis run, including scores, mentions, positions, and sentiment.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run details with individual prompt results per LLM" } } } }, "/projects/{id}/ideas": { "get": { "summary": "Suggested improvements", "description": "Today's new ideas and anything saved or in progress. Filter with status=new|saved|in_progress|done|dismissed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id" }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Ideas with evidence, outline, impact, effort, why it matters, and the latest outcome check." } } } }, "/projects/{id}/ideas/{ideaId}": { "patch": { "summary": "Save, start, finish or dismiss an idea", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id" }, { "name": "ideaId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Idea id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "saved", "in_progress", "done", "dismissed" ] }, "reason": { "type": "string", "enum": [ "not_relevant", "already_done", "too_much_effort", "disagree" ] }, "note": { "type": "string" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "The idea's new status. Marking done records a baseline; outcome checks follow at 7, 14, 28 and 42 days." } } } }, "/projects/{id}/ideas/{ideaId}/brief": { "get": { "summary": "Action brief for an idea", "description": "Written on first request (up to a minute), then stored.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id" }, { "name": "ideaId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Idea id" } ], "responses": { "200": { "description": "Markdown brief: objective, target page, what to include, facts to gather, structure, starter snippet, done-when checklist, sources." } } } }, "/projects/{id}/changes": { "get": { "summary": "What competitors changed", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id" }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 14, "maximum": 90 } }, { "name": "all", "in": "query", "schema": { "type": "boolean" }, "description": "Include minor changes" } ], "responses": { "200": { "description": "Major and notable change events, ranked." } } } }, "/projects/{id}/topics": { "get": { "summary": "Topic map", "description": "Coverage per site (pages, words, visibility, citations) and the research verdict per topic.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id" } ], "responses": { "200": { "description": "Sites and topics." } } } }, "/projects/{id}/competitors/{competitorId}/teardown": { "get": { "summary": "Why a competitor is ahead", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Project id" }, { "name": "competitorId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Competitor id" } ], "responses": { "200": { "description": "The latest teardown: verdict, threat level, findings with evidence, what you are missing, references." } } } } } }