{"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"]},"PlatformUnavailableError":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","const":"PLATFORM_UNAVAILABLE"},"platforms":{"type":"array","items":{"$ref":"#/components/schemas/PlatformId"}}},"required":["error","code","platforms"]},"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."},"ExecutionRoute":{"type":["object","null"],"description":"Actual execution route. Null means historical primary; never infer today's fallback for old rows.","properties":{"version":{"type":"integer","const":1},"source":{"type":"string","enum":["primary","api_fallback"]},"provider":{"type":"string"},"transport":{"type":"string","enum":["web","api","agent_api"]},"model":{"type":"string"},"responseId":{"type":"string"},"reason":{"type":"string"}},"required":["version","source","provider","transport"]},"PlatformAvailability":{"type":"object","description":"Runtime availability keyed by platform; distinct from entitlement and saved selections.","additionalProperties":{"type":"object","properties":{"platform":{"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."},"status":{"type":"string","enum":["available","api_fallback","unavailable"]},"primaryDisabled":{"type":"boolean"},"reason":{"type":"string"},"route":{"$ref":"#/components/schemas/ExecutionRoute"}},"required":["platform","status","primaryDisabled","route"]}},"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"}}}},"503":{"description":"A requested platform is unavailable, or an inherited scope has no available platforms (code PLATFORM_UNAVAILABLE; platforms lists affected ids). Update the requested scope before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformUnavailableError"}}}}}}},"/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"},"platforms":{"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,"description":"Optional explicit scope. Unavailable selections fail with PLATFORM_UNAVAILABLE; omitted scope uses available saved selections."}},"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"}}}},"503":{"description":"A requested platform is unavailable, or an inherited scope has no available platforms (code PLATFORM_UNAVAILABLE; platforms lists affected ids). Update the requested scope before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformUnavailableError"}}}}}},"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. Live count fields distinguish retrieved provider outputs from evidence-ready analyzed outputs. 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."},"cancelRequested":{"type":"boolean"},"totalTasks":{"type":"integer"},"completedTasks":{"type":"integer"},"retrievedTasks":{"type":"integer"},"analyzedTasks":{"type":"integer"},"settledTasks":{"type":"integer"},"failedTasks":{"type":"integer"},"pendingTasks":{"type":"integer"},"remainingTasks":{"type":"integer"},"cancelledTasks":{"type":"integer"},"incompleteTasks":{"type":"integer"},"extractionPendingTasks":{"type":"integer"},"extractionFailedTasks":{"type":"integer"},"extractionIncompleteTasks":{"type":"integer"},"scraperAttempted":{"type":"boolean"},"scraperSucceeded":{"type":"boolean"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"resultsRevision":{"type":"integer"}}}}}},"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/runs":{"get":{"tags":["Runs"],"summary":"List a project's prompt run history","description":"Returns paginated prompt runs with status, timestamps, platforms, and task totals. Use a completed run's id as runId on historical analytics reads.","parameters":[{"name":"projectId","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"Project id. Required on all data endpoints."},{"name":"status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["pending","running","completed","failed","interrupted"]}},"style":"form","explode":true,"description":"Repeat this parameter or provide comma-separated values to filter by run status."},{"name":"startedAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"startedBefore","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"completedAfter","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"completedBefore","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"triggeredBy","in":"query","required":false,"schema":{"type":"string","enum":["manual","scheduled"]}},{"name":"platform","in":"query","required":false,"schema":{"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."}},"style":"form","explode":true,"description":"Repeat this parameter or provide comma-separated values to filter by platform ID."},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["ordinal","status","startedAt","completedAt","duration"],"default":"ordinal"}},{"name":"sortDir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"ordinal":{"type":"integer"},"name":{"type":["string","null"]},"status":{"type":"string","enum":["pending","running","completed","failed","interrupted"]},"cancelRequested":{"type":"boolean"},"triggeredBy":{"type":"string","enum":["manual","scheduled"]},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"platforms":{"type":"array","items":{"type":"string"}},"excludedPlatforms":{"type":"array","items":{"type":"object","properties":{"platform":{"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."},"reason":{"type":"string"}},"required":["platform","reason"]},"description":"Unavailable platforms excluded from inherited scope; does not change saved project selections."},"totalTasks":{"type":["integer","null"]},"completedTasks":{"type":["integer","null"]},"failedTasks":{"type":["integer","null"]}},"required":["id","ordinal","name","status","cancelRequested","triggeredBy","startedAt","completedAt","platforms","totalTasks","completedTasks","failedTasks"]}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}},"required":["runs","total","limit","offset"]}}}},"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 or selected run","description":"Returns enriched platform responses (one per prompt × platform) with parse state plus trusted brand mentions, citations, and attributes. Pass runId to read a specific completed run, or pair it with allowIncompleteRun=1 for live partial results. Empty array when no usable run exists. API results include analyzed answers with exact executionRoute and model provenance.","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"},"description":"Prompt run ID. Omit to use the project's latest usable run. By default the run must be completed; pair with allowIncompleteRun=1 to read partial results from an owned in-progress, cancelled, or failed run. Use GET /prompts/runs to list run IDs."},{"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":"allowIncompleteRun","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Set to 1 with runId to read partial results from an owned run in any status. Unknown and other-project run IDs return an empty array in this mode."},{"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"},"executionRoute":{"$ref":"#/components/schemas/ExecutionRoute"},"executionSource":{"type":"string","enum":["primary","api_fallback"]},"executionLabel":{"type":"string"},"executionModel":{"type":["string","null"]},"legacyPrimary":{"type":"boolean"},"executionWarning":{"type":"string"},"executionDocsUrl":{"type":"string","format":"uri"},"requestedCountryCode":{"type":["string","null"]},"outcome":{"type":["string","null"]},"promptUsed":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"promptId":{"type":"string","format":"uuid"},"parseState":{"type":"string","enum":["pending","running","succeeded","failed","skipped"]},"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 or selected run","description":"Default returns an array of `VisibilityScore` (one per brand). Pass runId to read a specific completed run. 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":"runId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Completed prompt run ID. Omit to use the project's latest usable run; use GET /prompts/runs to list historical run IDs."},{"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 or selected run","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"},"description":"Completed prompt run ID. Omit to use the project's latest usable run; use GET /prompts/runs to list historical run IDs."},{"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 and run","description":"Synthesises visibility, attribute, and citation data for the topic into a 2–3 sentence actionable insight. Pass runId to read a specific completed run. 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":"runId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Completed prompt run ID. Omit to use the project's latest usable run; use GET /prompts/runs to list historical run IDs."},{"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":"runId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Completed prompt run ID. Omit to use the project's latest usable run; use GET /prompts/runs to list historical run IDs."},{"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 or selected run","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"},"description":"Completed prompt run ID. Omit to use the project's latest usable run; use GET /prompts/runs to list historical run IDs."},{"name":"allowIncompleteRun","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Set to 1 with runId to read trusted citations from an owned run in any status. Responses still awaiting or failing evidence extraction are excluded."},{"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"}},"platformAvailability":{"$ref":"#/components/schemas/PlatformAvailability"}},"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"}}}},"503":{"description":"A requested platform is unavailable, or an inherited scope has no available platforms (code PLATFORM_UNAVAILABLE; platforms lists affected ids). Update the requested scope before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformUnavailableError"}}}}}}},"/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"}}}},"409":{"description":"A live topic with this name already exists in the project","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"code":{"type":"string","enum":["topic_duplicate"]},"topic":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]},{"type":"null"}]}},"required":["code","topic"]}]}}}},"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"}},"platformAvailability":{"$ref":"#/components/schemas/PlatformAvailability"}},"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"}}}}}}}}}