{ "openapi": "3.1.0", "info": { "title": "OpenLens API", "version": "1.4.0", "description": "Public REST API for OpenLens. Onboard clients, run scans across the major AI platforms, read visibility metrics, and download client-ready reports. Beta — endpoints may evolve before GA.", "contact": { "name": "OpenLens support", "email": "contact@aibread.com" } }, "x-beta": true, "servers": [ { "url": "https://openlens.com/api" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Onboarding" }, { "name": "Runs" }, { "name": "Metrics" }, { "name": "Citations" }, { "name": "Deliverables" }, { "name": "Resources" }, { "name": "Account" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Clerk API key. Create one from your account settings under API Keys." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "description": "Stable machine code for programmatic handling, when applicable." } }, "required": [ "error" ] }, "PlatformId": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." }, "Brand": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "projectId": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "isOwn": { "type": "boolean" }, "aliases": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "isOwn" ] }, "Topic": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "projectId": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name" ] }, "Prompt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "topicId": { "type": "string", "format": "uuid" }, "topicName": { "type": "string" }, "promptTemplate": { "type": "string" }, "intentType": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "isManual": { "type": "boolean" }, "isActive": { "type": "boolean" }, "attributes": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "topicId", "promptTemplate", "isActive", "attributes" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "activePlatforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, "createdAt": { "type": "string", "format": "date-time" }, "ownBrandName": { "type": [ "string", "null" ] }, "ownBrandUrl": { "type": [ "string", "null" ] }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastRunStatus": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "VisibilityScore": { "type": "object", "properties": { "brandId": { "type": "string", "format": "uuid" }, "brandName": { "type": "string" }, "isOwn": { "type": "boolean" }, "overall": { "type": "number", "description": "Mention rate as a percentage (0–100)." }, "byPlatform": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Per-platform mention rate, keyed by platform id." }, "avgPosition": { "type": "number" }, "mentionCount": { "type": "integer" }, "totalPlatformResponses": { "type": "integer" }, "dominantSentiment": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "sentimentBreakdown": { "type": "object", "properties": { "positive": { "type": "integer" }, "neutral": { "type": "integer" }, "negative": { "type": "integer" } }, "required": [ "positive", "neutral", "negative" ] } }, "required": [ "brandId", "brandName", "isOwn", "overall", "byPlatform", "avgPosition", "mentionCount", "totalPlatformResponses", "dominantSentiment", "sentimentBreakdown" ] }, "TopicVisibility": { "type": "object", "properties": { "topicId": { "type": "string", "format": "uuid" }, "topicName": { "type": "string" }, "scores": { "type": "array", "items": { "$ref": "#/components/schemas/VisibilityScore" } } }, "required": [ "topicId", "topicName", "scores" ] }, "TopicVisibilitySummary": { "type": "object", "properties": { "topicId": { "type": "string", "format": "uuid" }, "topicName": { "type": "string" }, "ownVisibility": { "type": "number" }, "topCompetitor": { "type": "string" }, "topCompetitorVisibility": { "type": "number" } }, "required": [ "topicId", "topicName", "ownVisibility", "topCompetitor", "topCompetitorVisibility" ] }, "AttributeBreakdown": { "type": "object", "properties": { "attributeName": { "type": "string" }, "scores": { "type": "array", "items": { "type": "object", "properties": { "brandId": { "type": "string", "format": "uuid" }, "brandName": { "type": "string" }, "isOwn": { "type": "boolean" }, "avgSentiment": { "type": "number" }, "byPlatform": { "type": "object", "additionalProperties": { "type": "number" } }, "count": { "type": "integer" }, "contexts": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "context": { "type": "string" } }, "required": [ "platform", "context" ] } } }, "required": [ "brandId", "brandName", "isOwn", "avgSentiment", "byPlatform", "count", "contexts" ] } } }, "required": [ "attributeName", "scores" ] }, "TrendPoint": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "visibilityScore": { "type": "number" }, "avgPosition": { "type": "number" }, "mentionCount": { "type": "integer" }, "citationCount": { "type": "integer" }, "shareOfVoice": { "type": "number" }, "sentimentScore": { "type": "number" } } }, "TrendSummary": { "type": "object", "properties": { "currentScore": { "type": "number" }, "previousScore": { "type": "number" }, "changePercent": { "type": "number" }, "trend": { "type": "string", "enum": [ "up", "down", "flat" ] } }, "required": [ "currentScore", "previousScore", "changePercent", "trend" ] }, "TopSource": { "type": "object", "properties": { "domain": { "type": "string" }, "count": { "type": "integer" }, "platforms": { "type": "array", "items": { "type": "string" } }, "domainCategory": { "oneOf": [ { "type": "string", "enum": [ "own_brand", "competitor", "news", "ugc", "review_site", "third_party" ] }, { "type": "null" } ] }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "url", "count" ] } } }, "required": [ "domain", "count", "platforms", "urls" ] }, "TopicMentionGroup": { "type": "object", "properties": { "topicId": { "type": "string", "format": "uuid" }, "topicName": { "type": "string" }, "count": { "type": "integer" }, "platforms": { "type": "array", "items": { "type": "string" } }, "bestPosition": { "type": [ "integer", "null" ] }, "dominantSentiment": { "oneOf": [ { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, { "type": "null" } ] }, "urls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "domain": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "url", "domain", "count" ] } } }, "required": [ "topicId", "topicName", "count", "platforms", "urls" ] } } }, "paths": { "/onboard": { "post": { "tags": [ "Onboarding" ], "summary": "Analyze a brand or confirm a new project", "description": "Two-step onboarding over Server-Sent Events. `action: analyze` researches a URL and proposes competitors and topics. `action: confirm` creates the project and generates prompts.\n\nThe response stream emits `data:` lines with progress events followed by a final event with `status: \"complete\"` and the payload.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "analyze" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "action", "url" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "confirm" ] }, "brandName": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "industryType": { "type": "string", "enum": [ "saas", "media", "agency", "ecommerce", "other" ] }, "location": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] }, "competitors": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "name" ] } ] } }, "topicList": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": [ "string", "null" ] } }, "required": [ "name" ] } ] } }, "activePlatforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, "promptsPerTopic": { "type": "integer", "minimum": 1, "maximum": 30 }, "projectId": { "type": "string", "format": "uuid", "description": "Reuse an existing project instead of creating one." }, "promptAttributes": { "type": "array", "items": { "type": "string" } }, "generateBrandedPrompts": { "type": "boolean" } }, "required": [ "action", "brandName" ] } ] } } } }, "responses": { "200": { "description": "Server-Sent Events stream. The final event has `status: \"complete\"` with the result payload (analyze: brand/competitor/topic suggestions; confirm: `{ projectId }`).", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prompts/run": { "post": { "tags": [ "Runs" ], "summary": "Start (or resume) a prompt run", "description": "Kicks off a fresh scan across the project's active platforms. Returns immediately with a `runId`. If a previous run was interrupted, this resumes it instead of starting a new one. Concurrent runs against the same project return 409.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" } }, "required": [ "projectId" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running" ] }, "resumed": { "type": "boolean" } }, "required": [ "runId", "status" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A run is already in progress for this project.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "activeRunId": { "type": [ "string", "null" ], "format": "uuid" } } } ] } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Runs" ], "summary": "Cancel the running run for a project", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "projectId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prompts/status": { "get": { "tags": [ "Runs" ], "summary": "Poll the status of a run", "description": "Pass `runId` for a specific run, or only `projectId` to fetch the project's most recent run. Returns `status: \"none\"` when no run exists yet.", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "runId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "interrupted", "cancelled", "none" ], "description": "`cancelled` is reported by /prompts/status when a `failed` run had `cancelRequested = true`. `none` only appears when no run exists for the project." }, "totalTasks": { "type": "integer" }, "completedTasks": { "type": "integer" }, "failedTasks": { "type": "integer" }, "pendingTasks": { "type": "integer" }, "cancelledTasks": { "type": "integer" }, "incompleteTasks": { "type": "integer" }, "scraperAttempted": { "type": "boolean" }, "scraperSucceeded": { "type": "boolean" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prompts/results": { "get": { "tags": [ "Runs" ], "summary": "Raw platform responses from the latest usable run", "description": "Returns enriched platform responses (one per prompt × platform) with brand mentions, citations, and attributes attached. Empty array when no usable run exists.", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 500 } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "llmPlatform": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." }, "rawResponse": { "type": "string" }, "promptUsed": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "promptId": { "type": "string", "format": "uuid" }, "mentions": { "type": "array", "items": { "type": "object" } }, "citations": { "type": "array", "items": { "type": "object" } }, "attributes": { "type": "array", "items": { "type": "object" } } } } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/visibility": { "get": { "tags": [ "Metrics" ], "summary": "Visibility scores for the latest usable run", "description": "Default returns an array of `VisibilityScore` (one per brand). Use `type=topics` for a per-topic summary, `type=attributes&topicId=…` for a per-attribute breakdown, or `topicId=…` alone for a single topic's scores.", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "overview", "topics", "attributes" ], "default": "overview" } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "One of: array of VisibilityScore, array of TopicVisibilitySummary, TopicVisibility, or array of AttributeBreakdown depending on `type`.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/VisibilityScore" } }, { "type": "array", "items": { "$ref": "#/components/schemas/TopicVisibilitySummary" } }, { "$ref": "#/components/schemas/TopicVisibility" }, { "type": "array", "items": { "$ref": "#/components/schemas/AttributeBreakdown" } } ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/visibility/trends": { "get": { "tags": [ "Metrics" ], "summary": "Time-series visibility for a brand or all competitors", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "brandId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, { "name": "compare", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, include `competitorSeries` for every non-own brand in the project." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 90 } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": "array", "items": { "$ref": "#/components/schemas/TrendPoint" } }, "competitorSeries": { "type": "array", "items": { "type": "object", "properties": { "brandId": { "type": "string", "format": "uuid" }, "brandName": { "type": "string" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/TrendPoint" } } }, "required": [ "brandId", "brandName", "series" ] } }, "summary": { "$ref": "#/components/schemas/TrendSummary" } }, "required": [ "series", "summary" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/engines": { "get": { "tags": [ "Metrics" ], "summary": "Per-platform source behavior patterns for the latest run", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "Engine pattern record. Shape varies by platform; treat as opaque JSON." } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/insights/topic": { "get": { "tags": [ "Metrics" ], "summary": "AI-generated insight paragraph for one topic", "description": "Synthesises visibility, attribute, and citation data for the topic into a 2–3 sentence actionable insight. Returns 404 when the project has no usable run or the topic is unknown.", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "topicId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "insight": { "type": "string" } }, "required": [ "insight" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brand-mentions-summary": { "get": { "tags": [ "Citations" ], "summary": "Top topics where your own brand was mentioned, with the URLs cited", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 200 } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TopicMentionGroup" } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/sources": { "get": { "tags": [ "Citations" ], "summary": "Top cited domains for the latest run", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "own_brand", "competitor", "news", "ugc", "review_site", "third_party" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 500 } }, { "name": "urlsPerDomain", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 200 } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TopSource" } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/visibility": { "get": { "tags": [ "Deliverables" ], "summary": "Download a client-ready PDF visibility report", "description": "Renders a multi-page PDF for the chosen run. `runId` is required — the caller picks the run from `/reports/runs`. Optionally include the full per-prompt detail via `includePrompts=1`.", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "runId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "includePrompts", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1", "0", "true", "false", "yes", "no" ] } }, { "name": "promptAttributes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated list of attribute filters. Accepts both built-in attributes (e.g. `pricing`, `comparisons`) and project-specific custom attributes." } ], "responses": { "200": { "description": "PDF report.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/runs": { "get": { "tags": [ "Deliverables" ], "summary": "Recent run history for the report picker", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "triggeredBy": { "type": "string", "enum": [ "manual", "scheduled" ] }, "status": { "type": "string", "enum": [ "running", "completed", "failed", "interrupted", "cancelled", "none" ], "description": "`cancelled` is reported by /prompts/status when a `failed` run had `cancelRequested = true`. `none` only appears when no run exists for the project." }, "promptCount": { "type": "integer" } }, "required": [ "id", "startedAt", "status" ] } } }, "required": [ "runs" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects": { "get": { "tags": [ "Resources" ], "summary": "List your projects", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resources" ], "summary": "Create a new project", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "url": { "type": [ "string", "null" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}": { "put": { "tags": [ "Resources" ], "summary": "Update a project", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "languages": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Resources" ], "summary": "Archive a project (soft delete)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/platforms": { "get": { "tags": [ "Resources" ], "summary": "Get the project's active platforms and the caller's entitlement", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "activePlatforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, "availablePlatforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, "availableOptions": { "type": "array", "items": { "type": "object" } } }, "required": [ "activePlatforms", "availablePlatforms" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Resources" ], "summary": "Set the project's active platforms", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "activePlatforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." }, "minItems": 1 } }, "required": [ "activePlatforms" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "activePlatforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } } }, "required": [ "activePlatforms" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/schedule": { "get": { "tags": [ "Resources" ], "summary": "Get the project's scan schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "nextScheduledRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "pauseReason": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Resources" ], "summary": "Update the project's scan schedule", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 } }, "required": [ "enabled" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "frequency": { "type": "string", "enum": [ "daily", "weekly", "monthly" ] }, "hour": { "type": "integer" }, "nextScheduledRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "pauseReason": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/prompt-attributes": { "get": { "tags": [ "Resources" ], "summary": "List allowed prompt-attribute values for the project", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "includeArchived", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "builtIns": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "normalizedValue": { "type": "string" } }, "required": [ "value", "normalizedValue" ] } }, "languages": { "type": "array", "items": { "type": "object" } }, "customAttributes": { "type": "array", "items": { "type": "object" } }, "archivedCustomAttributes": { "type": "array", "items": { "type": "object" } }, "allowedAttributes": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resources" ], "summary": "Add a custom prompt-attribute value", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } }, "required": [ "value" ] } } } }, "responses": { "201": { "description": "Attribute created", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Resources" ], "summary": "Rename or archive an existing custom prompt-attribute", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nextValue": { "type": "string" }, "archived": { "type": "boolean" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Resources" ], "summary": "Archive a custom prompt-attribute by value", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "value", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/brands": { "get": { "tags": [ "Resources" ], "summary": "List brands in a project (your own + competitors)", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resources" ], "summary": "Add a brand (competitor or own)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "isOwn": { "type": "boolean" }, "projectId": { "type": "string", "format": "uuid" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Brand created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Resources" ], "summary": "Update a brand's aliases", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "aliases": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "aliases" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Resources" ], "summary": "Delete a brand", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/topics": { "get": { "tags": [ "Resources" ], "summary": "List topics in a project", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Topic" } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resources" ], "summary": "Create a topic; prompts are generated in the background", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "category": { "type": [ "string", "null" ] }, "projectId": { "type": "string", "format": "uuid" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Topic created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Topic" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Resources" ], "summary": "Delete a topic and its prompts", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/prompts": { "get": { "tags": [ "Resources" ], "summary": "List prompts, optionally filtered by topic or fetched by id", "parameters": [ { "name": "projectId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Project id. Required on all data endpoints." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "promptId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/Prompt" } }, { "$ref": "#/components/schemas/Prompt" } ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Resources" ], "summary": "Create a prompt under a topic", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topicId": { "type": "string", "format": "uuid" }, "promptTemplate": { "type": "string" }, "language": { "type": [ "string", "null" ] }, "attributes": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Optional. Omitting the key is the same as sending []. When present, must be an array of attributes from the project's allowed list." } }, "required": [ "topicId", "promptTemplate" ] } } } }, "responses": { "201": { "description": "Prompt created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Prompt" } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Resources" ], "summary": "Update prompt text, attributes, or active flag", "description": "Editing prompt text after results exist requires an explicit choice. The first call returns 409 with `requiresConfirmation: true` (plus `tracked` and `inFlightRun` hints); resend with `confirmClone: true` to clone-and-supersede (the original is deactivated with its history intact — recommended for tracked prompts) or `confirmOverwrite: true` to edit in place (unavailable while a run is in flight).", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "promptTemplate": { "type": "string" }, "attributes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "confirmClone": { "type": "boolean" }, "confirmOverwrite": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Prompt" }, { "type": "object", "properties": { "cloned": { "type": "boolean" }, "originalPromptId": { "type": "string", "format": "uuid" } } } ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Resources" ], "summary": "Soft-delete a prompt", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me/limits": { "get": { "tags": [ "Account" ], "summary": "Return the caller's effective rate limits and quotas", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "Effective limits applied to the caller (project cap, daily run cap, max prompts, etc). Shape mirrors `getEffectiveLimits` internal helper.", "additionalProperties": true } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "tags": [ "Account" ], "summary": "Token usage and scraper spend, aggregated by model and call type", "parameters": [ { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "promptRunId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalInputTokens": { "type": "integer" }, "totalOutputTokens": { "type": "integer" }, "totalWebSearches": { "type": "integer" }, "llmCostUsd": { "type": "number" }, "bdSpendUsd": { "type": "number" }, "totalSpendUsd": { "type": "number" }, "byModel": { "type": "array", "items": { "type": "object" } }, "byCallType": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settings/schedule": { "get": { "tags": [ "Account" ], "summary": "Deprecated: schedule lives on the project (410 Gone)", "description": "Use `/projects/{id}/schedule` instead.", "responses": { "410": { "description": "Endpoint removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/settings/platforms": { "get": { "tags": [ "Account" ], "summary": "List the caller's allowed platforms (read-only entitlement)", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "availablePlatforms": { "type": "array", "items": { "type": "string", "enum": [ "chatgpt", "chatgpt_app", "claude", "gemini", "gemini_app", "grok_app", "grok_api", "perplexity", "perplexity_app", "google_app", "deepseek" ], "description": "LLM platform identifier. Newer scraper-backed ids end in `_app`; `chatgpt`, `perplexity`, and `gemini` are legacy and not returned by current runs." } }, "availableOptions": { "type": "array", "items": { "type": "object" } } }, "required": [ "availablePlatforms" ] } } } }, "400": { "description": "Missing or invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, malformed, or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Monthly included API calls for your tier are used up (code `USAGE_LIMIT`). Body includes a `limit` object — `{ limitHit, currentTier, targetTier, feature, cap, used, resetAt }` — describing the cap and the upgrade that lifts it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found or not owned by your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit, project cap, or daily quota hit. Body includes a `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error. Retry; if persistent, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }