{"openapi":"3.1.1","info":{"title":"Notra API","version":"1.0.0","description":"OpenAPI schema for Notra content endpoints. Use GET /v1/status for public reachability. Error responses include recovery guidance. Breaking changes ship under a new major path; deprecated operations send Deprecation and Sunset headers at least 90 days before removal."},"externalDocs":{"description":"Notra API versioning and deprecation policy","url":"https://www.usenotra.com/docs/api/versioning"},"servers":[{"url":"https://api.usenotra.com","description":"Production"},{"url":"https://demo-api.usenotra.com","description":"Sandbox with sample data. Get a free sandbox key at demo.usenotra.com, no signup needed"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Webhooks","description":"Manage outbound webhook subscriptions and delivery history."},{"name":"Discovery","description":"Public API status and authenticated workspace discovery."},{"name":"Content","description":"Manage posts, brand identities, and GitHub or Linear integrations, and queue content generation. Organization is inferred from the API key (identity.externalId)."},{"name":"Schedules","description":"Manage scheduled content generation. Organization is inferred from the API key (identity.externalId)."},{"name":"Event Triggers","description":"Manage event-based content generation triggered by GitHub webhooks. Organization is inferred from the API key (identity.externalId)."},{"name":"Chats","description":"Manage chat sessions. Organization is inferred from the API key (identity.externalId)."},{"name":"Skills","description":"Manage reusable writing skills. Organization is inferred from the API key (identity.externalId)."},{"name":"Feedback","description":"Collect and triage feedback submitted by AI agents. Agents post to the organization's feedback URL without credentials; reading and triage require an API key with feedback.read or feedback.write."},{"name":"GEO","description":"Manage generative engine optimization: projects, tracking settings, prompts, prompt sequences, competitors, scans, visibility reads, content gaps and briefs, agent readiness and AI traffic. Project-scoped endpoints require the GEO plan entitlement in addition to their scope; organization-level ingest endpoints require only the traffic scope."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Send your API key in the Authorization header as Bearer API_KEY. Account API keys work in every workspace you belong to: send X-Notra-Organization-Id with the workspace id or slug to choose one. Workspace endpoints require it when you belong to more than one workspace; GET /v1/me/workspaces works without it. Organization keys only accept their own workspace there."}},"parameters":{"OrganizationSelector":{"name":"X-Notra-Organization-Id","in":"header","required":false,"description":"Workspace id or slug an account API key acts on. Required on workspace endpoints when the key's user belongs to more than one workspace; GET /v1/me/workspaces works without it. Organization keys reject any other workspace; OAuth tokens ignore it.","schema":{"type":"string"}}},"schemas":{"PublicStatusResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"service":{"type":"string","enum":["Notra API"]},"version":{"type":"string"},"public":{"type":"boolean","enum":[true]},"authentication":{"type":"object","properties":{"type":{"type":"string","enum":["bearer"]},"resource_metadata":{"type":"string","format":"uri"},"guide":{"type":"string","format":"uri"}},"required":["type","resource_metadata","guide"]}},"required":["status","service","version","public","authentication"]},"RateLimitErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"limit":{"type":"integer","minimum":1},"remaining":{"type":"integer","minimum":0},"reset":{"type":"integer"}},"required":["error","limit","remaining","reset"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"recovery":{"type":"string"}},"required":["error"]},"PostScheduleResponse":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"schedule":{"$ref":"#/components/schemas/PostSchedule"}},"required":["organization","schedule"]},"PostSchedule":{"type":["object","null"],"properties":{"postId":{"type":"string"},"scheduledAt":{"type":"string","format":"date-time"},"timeZone":{"type":"string"},"publications":{"type":"array","items":{"$ref":"#/components/schemas/ScheduledPublication"}}},"required":["postId","scheduledAt","timeZone","publications"]},"ScheduledPublication":{"type":"object","properties":{"id":{"type":"string"},"destination":{"type":"string","enum":["notra","github","social"]},"config":{"oneOf":[{"type":"object","properties":{"destination":{"type":"string","enum":["notra"]}},"required":["destination"]},{"type":"object","properties":{"destination":{"type":"string","enum":["github"]},"repositoryId":{"type":"string"},"merge":{"type":"boolean"}},"required":["destination","repositoryId","merge"]},{"type":"object","properties":{"destination":{"type":"string","enum":["social"]},"accountId":{"type":"string"}},"required":["destination","accountId"]}]},"status":{"type":"string","enum":["scheduled","publishing","published","failed","canceled"],"description":"scheduled → publishing → published or failed. Failed destinations are retried automatically for transient errors before they end up failed."},"scheduledAt":{"type":"string","format":"date-time"},"timeZone":{"type":"string"},"attempts":{"type":"integer"},"errorCode":{"type":["string","null"]},"lastError":{"type":["string","null"]},"resultUrl":{"type":["string","null"],"description":"Pull request or social post URL once published."},"publishedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","destination","config","status","scheduledAt","timeZone","attempts","errorCode","lastError","resultUrl","publishedAt"]},"SchedulePostRequest":{"type":"object","properties":{"scheduledAt":{"type":"string","format":"date-time","description":"When to publish, as an ISO 8601 timestamp. At most one year ahead; a time up to five minutes in the past publishes right away.","example":"2026-10-06T08:00:00Z"},"timeZone":{"type":"string","minLength":1,"maxLength":100,"default":"UTC","description":"IANA time zone the schedule was picked in. Used for display and emails only.","example":"Europe/Berlin"},"destinations":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleDestination"},"maxItems":2,"default":[],"description":"Where the post goes out besides Notra. The post is always marked as published in Notra at the scheduled time."}},"required":["scheduledAt"]},"ScheduleDestination":{"oneOf":[{"type":"object","properties":{"destination":{"type":"string","enum":["github"]},"repositoryId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"GitHub integration ID from GET /v1/integrations. Only for blog posts and changelogs.","example":"int_123"},"merge":{"type":"boolean","default":true,"description":"Merge the pull request at the scheduled time. When false, the pull request is only opened or updated."}},"required":["destination","repositoryId"]},{"type":"object","properties":{"destination":{"type":"string","enum":["social"]},"accountId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"Connected X or LinkedIn account ID. Only for tweets and LinkedIn posts, on an account of the matching platform.","example":"acc_123"}},"required":["destination","accountId"]}]},"CancelPostScheduleResponse":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"canceled":{"type":"integer","description":"Destinations that were canceled or cleared."},"inProgress":{"type":"boolean","description":"True when a destination was already publishing; it cannot be stopped and finishes on its own."}},"required":["organization","canceled","inProgress"]},"PostAgentReachResponse":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"agentReach":{"$ref":"#/components/schemas/PostAgentReach"}},"required":["organization","agentReach"]},"PostAgentReach":{"type":["object","null"],"properties":{"postId":{"type":"string"},"siteId":{"type":"string"},"path":{"type":"string","description":"Path the post is served at on its Site. Visits to its Markdown copy (`<path>.md`) and index files are counted too.","example":"/blog/launch"},"url":{"type":"string","example":"https://example.com/blog/launch"},"configured":{"type":"boolean","description":"False when the traffic backend is not configured for this deployment; the payload is then empty rather than an error."},"totals":{"type":"object","properties":{"crawled":{"type":"integer","description":"Training and search-index crawler visits."},"cited":{"type":"integer","description":"Visits from assistants reading the page while answering someone."},"referred":{"type":"integer","description":"People who clicked through from an AI answer."},"total":{"type":"integer"}},"required":["crawled","cited","referred","total"]},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"visitorType":{"type":"string","enum":["crawler","ai_referral","human","unknown"]},"agent":{"type":"string"},"category":{"type":"string"},"confidence":{"type":"string"},"visits":{"type":"integer"},"previousVisits":{"type":"integer"},"markdownVisits":{"type":"integer"},"previousMarkdownVisits":{"type":"integer"},"paths":{"type":"integer"},"previousPaths":{"type":"integer"},"lastSeenAt":{"type":"string"}},"required":["source","visitorType","agent","category","confidence","visits","markdownVisits","paths","lastSeenAt"]}},"points":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"visitorType":{"type":"string","enum":["crawler","ai_referral","human","unknown"]},"source":{"type":"string"},"visits":{"type":"integer"}},"required":["day","visitorType","source","visits"]}}},"required":["postId","siteId","path","url","configured","totals","sources","points"],"description":"Null when the post isn't live on a Notra Site: never published to one, published to another branch, or the Site has no production deployment."},"PatchScheduleRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Display name shown in the dashboard.","example":"Weekly changelog"},"sourceType":{"type":"string","enum":["cron"],"description":"Always cron for schedules."},"sourceConfig":{"type":"object","properties":{"cron":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","custom"],"description":"How often the schedule runs.","example":"weekly"},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day to run, in UTC (0-23).","example":9},"minute":{"type":"integer","minimum":0,"maximum":59,"description":"Minute of the hour to run (0-59).","example":0},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"Day of the week for weekly schedules, 0 (Sunday) to 6 (Saturday). Required when frequency is weekly.","example":1},"dayOfMonth":{"type":"integer","minimum":1,"maximum":31,"description":"Day of the month for monthly schedules (1-31). Required when frequency is monthly.","example":1},"intervalDays":{"type":"integer","minimum":2,"maximum":90,"description":"Run every N days (2-90). Required when frequency is custom.","example":3},"anchorDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC calendar date (YYYY-MM-DD) a custom interval counts from. Defaults to today.","example":"2026-09-03"}},"required":["frequency","hour","minute"]}},"required":["cron"],"description":"Replaces the cron settings as a whole. Send every cron field the frequency needs."},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"description":"GitHub integration IDs to generate from, as returned in the github array of GET /v1/integrations. Replaces the current GitHub targets; omit to keep them."},"linearIntegrationIds":{"type":"array","items":{"type":"string","minLength":1},"description":"Linear integration IDs to generate from, as returned in the linear array of GET /v1/integrations. When omitted, runs read every enabled Linear integration; send [] to read none. Replaces the current Linear targets; omit to keep them, send [] to remove them."}},"description":"Data source changes. The schedule must keep at least one GitHub or Linear integration."},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"],"description":"Type of content each run generates.","example":"changelog"},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":["string","null"],"enum":["webflow","framer","custom",null],"description":"Where auto-published posts are sent."},"brandVoiceId":{"type":["string","null"],"minLength":1,"description":"Brand identity ID to write in. Defaults to the organization's default brand identity.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"instructions":{"type":["string","null"],"minLength":1,"maxLength":2000,"description":"Free-text brief for this schedule, passed to the writer on every run on top of the brand's custom instructions. Use it to steer the angle of the content, for example tutorial-style blog posts.","example":"Write a tutorial-style post that walks through one feature shipped in this window, with code samples."},"notify":{"type":["object","null"],"properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"],"description":"Where to announce new content after a successful run: Slack posts to the organization's notification channel, email goes to the workspace owners.","example":{"slack":true,"email":false}}},"description":"Output setting changes, merged field by field into the current settings. Set a field to null to clear it, or send null to clear all of them."},"enabled":{"type":"boolean","description":"Whether the schedule runs. Disabled schedules are stored but never fire.","example":true},"autoPublish":{"type":"boolean","description":"Publish generated posts automatically instead of saving them as drafts."},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"],"description":"How far back each run collects source activity."}}},"PatchEventTriggerRequest":{"type":"object","properties":{"sourceType":{"type":"string","enum":["github_webhook"]},"sourceConfig":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"string","enum":["release","push"]},"minItems":1},"includePreReleases":{"type":"boolean","default":true},"ignoreCommitPatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"default":[]}},"required":["eventTypes"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":"object","properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"]},"brandVoiceId":{"type":"string","minLength":1},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"]}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean","default":false}},"required":["sourceType","sourceConfig","targets","outputType","enabled"]},"GetChatsResponse":{"type":"object","properties":{"chats":{"type":"array","items":{"$ref":"#/components/schemas/ChatSessionSummary"}}},"required":["chats"]},"ChatSessionSummary":{"type":"object","properties":{"chatId":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"pinnedAt":{"type":["string","null"]},"externalChannelId":{"$ref":"#/components/schemas/ExternalChannelId"}},"required":["chatId","title","createdAt","updatedAt","pinnedAt"]},"ExternalChannelId":{"type":["object","null"],"properties":{"source":{"type":"string","enum":["discord","slack","dashboard","agent"]},"id":{"type":"string","maxLength":200}},"required":["source"]},"GetChatResponse":{"type":"object","properties":{"chat":{"$ref":"#/components/schemas/ChatSessionSummary"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}},"required":["chat","messages"]},"ChatMessage":{},"SendChatMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":50000,"description":"The user message to send.","example":"Summarize what shipped in the last week."},"approvals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":500},"approved":{"type":"boolean"},"reason":{"type":"string","maxLength":2000}},"required":["id","approved"]},"minItems":1,"maxItems":50,"description":"Respond to every pending tool approval in the latest assistant message. Send either message or approvals. Only supported on an existing chat."},"model":{"type":"string","enum":["auto","zai/glm-5.3","zai/glm-5.3-flash","anthropic/claude-opus-5.5","anthropic/claude-opus-5","anthropic/claude-opus-4.8","anthropic/claude-sonnet-5","anthropic/claude-sonnet-4.6","anthropic/claude-haiku-4.5","openai/gpt-6-sol","openai/gpt-6-luna","openai/gpt-5.6-sol","openai/gpt-5.5","openai/gpt-5.4"],"description":"Deprecated and ignored. Chats always respond with GLM 5.3 Flash.","deprecated":true,"example":"zai/glm-5.3-flash"},"enableThinking":{"type":"boolean","description":"Allow the model to reason before answering.","example":false},"thinkingLevel":{"type":"string","enum":["off","low","medium","high"],"description":"How much reasoning effort to spend when thinking is enabled.","example":"medium"},"timezone":{"type":"string","minLength":1,"maxLength":100,"description":"IANA time zone used to interpret dates in the conversation.","example":"Europe/Berlin"},"context":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["github-repo"]},"integrationId":{"type":"string"},"owner":{"type":"string"},"repo":{"type":"string"}},"required":["type","integrationId","owner","repo"]},{"type":"object","properties":{"type":{"type":"string","enum":["linear-team"]},"integrationId":{"type":"string"},"teamName":{"type":"string"}},"required":["type","integrationId"]},{"type":"object","properties":{"type":{"type":"string","enum":["mcp-server"]},"integrationId":{"type":"string"},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["type","integrationId","name"]}]},"description":"Integrations the assistant may use as tools in this chat: connected GitHub repositories, Linear teams, or MCP servers."},"externalChannelId":{"$ref":"#/components/schemas/PublicExternalChannelId"}}},"PublicExternalChannelId":{"type":"object","properties":{"source":{"type":"string","enum":["discord","slack","dashboard"]},"id":{"type":"string","maxLength":200}},"required":["source"],"description":"Link the chat to a Discord or Slack channel, or tag it with your own dashboard id, so it can be found later with GET /v1/chats/by-external."},"ListSkillsResponse":{"type":"object","properties":{"skills":{"type":"array","items":{"$ref":"#/components/schemas/SkillSummary"}}},"required":["skills"]},"SkillSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"isSystem":{"type":"boolean","description":"True for built-in skills provided by Notra. System skills cannot be renamed or deleted."},"updatedAt":{"type":"string"}},"required":["id","name","description","isSystem","updatedAt"]},"SkillResponse":{"type":"object","properties":{"skill":{"$ref":"#/components/schemas/Skill"}},"required":["skill"]},"Skill":{"allOf":[{"$ref":"#/components/schemas/SkillSummary"},{"type":"object","properties":{"content":{"type":"string"},"createdAt":{"type":"string"}},"required":["content","createdAt"]}]},"CreateSkillResponse":{"type":"object","properties":{"skill":{"$ref":"#/components/schemas/Skill"}},"required":["skill"]},"CreateSkillRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Skill name. Lowercase letters, digits, and hyphens only.","example":"humanizer"},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Short description of when the skill should be used.","example":"Polish near-final drafts so they sound natural and specific."},"content":{"type":"string","minLength":1,"maxLength":200000,"description":"Full skill instructions, typically Markdown.","example":"# Humanizer\n\nRewrite the draft so it reads like a person wrote it. Remove filler, vary sentence length, and keep concrete details."}},"required":["name","description","content"]},"PatchSkillResponse":{"type":"object","properties":{"skill":{"$ref":"#/components/schemas/Skill"}},"required":["skill"]},"PatchSkillRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Skill name. Lowercase letters, digits, and hyphens only.","example":"humanizer"},"description":{"type":"string","minLength":1,"maxLength":1000,"description":"Short description of when the skill should be used.","example":"Polish near-final drafts so they sound natural and specific."},"content":{"type":"string","minLength":1,"maxLength":200000,"description":"Full skill instructions, typically Markdown.","example":"# Humanizer\n\nRewrite the draft so it reads like a person wrote it. Remove filler, vary sentence length, and keep concrete details."}}},"DeleteSkillResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]}},"required":["success"]},"GetWorkspacesResponse":{"type":"object","properties":{"currentWorkspace":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"workspaces":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]},"role":{"type":["string","null"]},"status":{"type":"string","enum":["active","pending"]},"isCurrent":{"type":"boolean"}},"required":["id","slug","name","logo","role","status","isCurrent"]}},"authentication":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["apiKey"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["oauth"]},"accountId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["type","accountId","scopes"]}]}},"required":["currentWorkspace","workspaces","authentication"]},"SubmitFeedbackResponse":{"type":"object","properties":{"feedback":{"$ref":"#/components/schemas/Feedback"},"deduplicated":{"type":"boolean","description":"True when an existing feedback with the same idempotencyKey was returned."}},"required":["feedback","deduplicated"]},"Feedback":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":["string","null"]},"source":{"type":"string","enum":["mcp","api","sdk"],"description":"Channel the feedback arrived through.","example":"mcp"},"kind":{"type":"string","enum":["bug","feature","praise","question","other"],"description":"What kind of feedback this is.","example":"bug"},"sentiment":{"type":["string","null"],"enum":["negative","neutral","positive",null],"description":"Overall sentiment of the feedback.","example":"negative"},"status":{"type":"string","enum":["new","triaged","resolved","archived"],"description":"Triage status.","example":"new"},"title":{"type":["string","null"]},"message":{"type":"string"},"agentClient":{"type":["string","null"]},"agentModel":{"type":["string","null"]},"toolVersion":{"type":["string","null"]},"userAgent":{"type":["string","null"]},"contextUrl":{"type":["string","null"]},"externalId":{"type":["string","null"]},"idempotencyKey":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{}},"resolvedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","projectId","source","kind","sentiment","status","title","message","agentClient","agentModel","toolVersion","userAgent","contextUrl","externalId","idempotencyKey","metadata","resolvedAt","createdAt","updatedAt"]},"SubmitFeedbackRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":4000,"description":"The feedback itself.","example":"The search tool times out when the query has quotes."},"title":{"type":"string","minLength":1,"maxLength":200,"description":"Short summary. When omitted, Notra writes one.","example":"Search times out on quoted queries"},"kind":{"type":"string","enum":["bug","feature","praise","question","other"],"description":"What kind of feedback this is. When omitted, Notra classifies it.","example":"bug"},"sentiment":{"type":"string","enum":["negative","neutral","positive"],"description":"Overall sentiment. When omitted, Notra classifies it from the message.","example":"negative"},"source":{"type":"string","enum":["mcp","api","sdk"],"default":"api","description":"Channel the feedback arrived through.","example":"mcp"},"projectId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"Project to file the feedback under."},"agentClient":{"type":"string","minLength":1,"maxLength":200,"description":"The agent or client that submitted the feedback.","example":"claude-code"},"agentModel":{"type":"string","minLength":1,"maxLength":200,"example":"claude-opus-5"},"toolVersion":{"type":"string","minLength":1,"maxLength":200,"example":"1.2.0"},"userAgent":{"type":"string","minLength":1,"maxLength":2048},"contextUrl":{"type":"string","maxLength":2048,"format":"uri","description":"Page or resource the feedback is about.","example":"https://docs.example.com/api/search"},"externalId":{"type":"string","minLength":1,"maxLength":200,"description":"Your own identifier for the user or session."},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200,"description":"Submitting the same key twice returns the original feedback instead of creating a duplicate."},"metadata":{"type":"object","additionalProperties":{},"description":"Arbitrary JSON attached to the feedback, up to 8 KB."}},"required":["message"]},"ListFeedbackResponse":{"type":"object","properties":{"feedback":{"type":"array","items":{"$ref":"#/components/schemas/Feedback"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"currentPage":{"type":"integer","minimum":1},"nextPage":{"type":["integer","null"],"minimum":1},"previousPage":{"type":["integer","null"],"minimum":1},"totalPages":{"type":"integer","minimum":1},"totalItems":{"type":"integer","minimum":0}},"required":["limit","currentPage","nextPage","previousPage","totalPages","totalItems"]}},"required":["feedback","pagination"]},"FeedbackResponse":{"type":"object","properties":{"feedback":{"$ref":"#/components/schemas/Feedback"}},"required":["feedback"]},"UpdateFeedbackRequest":{"type":"object","properties":{"status":{"type":"string","enum":["new","triaged","resolved","archived"],"description":"Triage status.","example":"new"}},"required":["status"]},"ListGeoProjectsResponse":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/GeoProject"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["projects","organization"]},"GeoProject":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brandSettingsId":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","brandSettingsId","createdAt"]},"GeoProjectResponse":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/GeoProject"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["project","organization"]},"CreateGeoProjectRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"brandSettingsId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"Brand identity to link. Defaults to the organization's default identity."}},"required":["name"]},"PatchGeoProjectRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"brandSettingsId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"}}},"DeleteGeoProjectResponse":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","organization"]},"GeoSettingsResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"Whether the analytics backend is configured."},"settings":{"$ref":"#/components/schemas/GeoSettings"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","settings","organization"]},"GeoSettings":{"type":["object","null"],"properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"projectId":{"type":"string"},"companyName":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"conversionPaths":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"competitors":{"type":"array","items":{"type":"string"}},"languages":{"type":"array","items":{"type":"string"}},"engines":{"type":"array","items":{"type":"string"}},"enforceZdr":{"type":"boolean"},"nonZdrApprovedEngines":{"type":"array","items":{"type":"string"}},"trackWithoutSearch":{"type":"boolean"},"pausedAutoPromptIds":{"type":"array","items":{"type":"string"}},"removedAutoPromptIds":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"scanIntervalHours":{"type":"integer"},"scanStartedAt":{"type":["string","null"]},"lastScanAt":{"type":["string","null"]},"isScanning":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","projectId","companyName","aliases","conversionPaths","domains","competitors","languages","engines","enforceZdr","nonZdrApprovedEngines","trackWithoutSearch","pausedAutoPromptIds","removedAutoPromptIds","enabled","scanIntervalHours","scanStartedAt","lastScanAt","isScanning","createdAt","updatedAt"]},"GeoEngineListResponse":{"type":"object","properties":{"engines":{"type":"array","items":{"$ref":"#/components/schemas/GeoEngine"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["engines","organization"]},"GeoEngine":{"type":"object","properties":{"id":{"type":"string","description":"Engine id to pass in the `engines` setting.","example":"google/ai-overview"},"label":{"type":"string"},"provider":{"type":"string"},"zdr":{"type":"string","enum":["all","some","none"],"description":"Zero data retention coverage. Engines with `none` need `enforceZdr: false` or an entry in `nonZdrApprovedEngines`."},"default":{"type":"boolean","description":"Part of the default engine set for new projects."},"supportsGroundedChecks":{"type":"boolean"}},"required":["id","label","provider","zdr","default","supportsGroundedChecks"]},"PatchGeoSettingsRequest":{"type":"object","properties":{"companyName":{"type":"string","minLength":1,"maxLength":128},"aliases":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":10},"conversionPaths":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":20,"description":"Paths that count as a conversion when an AI referral reaches them. Prefix match. Omit to keep the stored list."},"domains":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":20,"description":"Additional hostnames that send AI traffic to this project, besides the brand website. Subdomains of a listed domain are included. Omit to keep the stored list."},"languages":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":4},"engines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":64},"enforceZdr":{"type":"boolean"},"nonZdrApprovedEngines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":64},"trackWithoutSearch":{"type":"boolean","description":"Also scan search-capable models without web search. Omit to keep the stored value (default false)."},"pausedAutoPromptIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":8,"description":"Ids of auto-generated prompts to skip in scans. Omit to keep the current list."},"removedAutoPromptIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":8,"description":"Ids of auto-generated prompts removed from tracking. Omit to keep the current list."},"enabled":{"type":"boolean"},"scanIntervalHours":{"type":"integer","minimum":24,"maximum":2160,"description":"Hours between automatic scans, 24-2160, in whole days (multiple of 24). Presets: 24, 48, 72, 168, 336, 720."}},"required":["companyName","aliases","languages","engines","enforceZdr","nonZdrApprovedEngines","enabled","scanIntervalHours"]},"ListGeoPromptsResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"prompts":{"type":"array","items":{"$ref":"#/components/schemas/GeoPrompt"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","prompts","organization"]},"GeoPrompt":{"type":"object","properties":{"id":{"type":"string"},"prompt":{"type":"string"},"enabled":{"type":"boolean"},"source":{"type":"string","enum":["custom","auto"]},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":["string","null"]}},"required":["id","prompt","enabled","source","tags","createdAt"]},"GeoPromptResponse":{"type":"object","properties":{"prompt":{"$ref":"#/components/schemas/GeoPrompt"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["prompt","organization"]},"CreateGeoPromptRequest":{"type":"object","properties":{"prompt":{"type":"string","minLength":8,"maxLength":300},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20,"description":"Free-form labels for grouping custom prompts. Lowercased and deduplicated on save."}},"required":["prompt"]},"PatchGeoPromptRequest":{"type":"object","properties":{"enabled":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20,"description":"Free-form labels for grouping custom prompts. Lowercased and deduplicated on save."}}},"DeleteGeoPromptResponse":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","organization"]},"ImportGeoPromptsResponse":{"type":"object","properties":{"imported":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"issues":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"message":{"type":"string"}},"required":["line","message"]},"description":"Rows rejected while parsing CSV. Always empty for `rows`."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["imported","updated","skipped","issues","organization"]},"ImportGeoPromptsRequest":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"prompt":{"type":"string","minLength":8,"maxLength":300},"enabled":{"type":"boolean"}},"required":["prompt"]},"minItems":1,"maxItems":500},"csv":{"type":"string","minLength":1,"maxLength":1048576,"description":"Raw CSV text with a `prompt` column (optionally `enabled`). Used when `rows` is omitted."}}},"ListGeoPromptSuggestionsResponse":{"type":"object","properties":{"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/GeoPromptSuggestion"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["suggestions","organization"]},"GeoPromptSuggestion":{"type":"object","properties":{"id":{"type":"string"},"prompt":{"type":"string"},"title":{"type":["string","null"]},"source":{"type":"string","enum":["search_console"]},"keywords":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"clicks":{"type":"number"},"impressions":{"type":"number"},"position":{"type":"number"}},"required":["query","clicks","impressions","position"]},"description":"Search Console queries the suggestion was derived from."},"createdAt":{"type":"string"}},"required":["id","prompt","title","source","keywords","createdAt"]},"DismissGeoPromptSuggestionResponse":{"type":"object","properties":{"id":{"type":"string"},"dismissed":{"type":"boolean"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","dismissed","organization"]},"ListGeoSequencesResponse":{"type":"object","properties":{"sequences":{"type":"array","items":{"$ref":"#/components/schemas/GeoSequence"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["sequences","organization"]},"GeoSequence":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","name","steps","enabled","createdAt"]},"GeoSequenceResponse":{"type":"object","properties":{"sequence":{"$ref":"#/components/schemas/GeoSequence"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["sequence","organization"]},"CreateGeoSequenceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"steps":{"type":"array","items":{"type":"string","minLength":8,"maxLength":300},"minItems":1,"maxItems":5}},"required":["name","steps"]},"PatchGeoSequenceRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"steps":{"type":"array","items":{"type":"string","minLength":8,"maxLength":300},"minItems":1,"maxItems":5},"enabled":{"type":"boolean"}}},"DeleteGeoSequenceResponse":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","organization"]},"RunGeoSequenceResponse":{"type":"object","properties":{"checks":{"type":"integer","description":"Answers recorded during this request by the API-based engines that responded. Consumer-app answers from the queued scan are not counted."},"mentions":{"type":"integer","description":"How many of those answers mentioned the tracked brand."},"engines":{"type":"array","items":{"type":"string"},"description":"API-based engines that answered the conversation during this request. Empty when only consumer apps run or none of the API engines answered."},"queuedScanId":{"type":["string","null"],"default":null,"description":"Scan that plays the conversation in the tracked consumer apps (ChatGPT, Perplexity, Gemini, AI Mode, Copilot) in the background, or `null` when none was queued. Poll `GET /v1/projects/{projectId}/geo/scans/{scanId}` until `status` leaves `running`; its answers then land in the project's GEO checks."},"queuedEngines":{"type":"array","items":{"type":"string"},"default":[],"description":"Consumer-app engines covered by `queuedScanId`. Empty when nothing was queued."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["checks","mentions","engines","organization"]},"ListGeoPersonasResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"personas":{"type":"array","items":{"$ref":"#/components/schemas/GeoPersona"},"description":"Active personas first in creation order, then archived ones. A project keeps at most 5 active personas."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","personas","organization"]},"GeoPersona":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","description":"Buyer archetype label, such as Budgeter."},"role":{"type":"string"},"company":{"type":"string"},"summary":{"type":"string"},"searchStyle":{"type":"string"},"profile":{"type":"object","properties":{"goals":{"type":"array","items":{"type":"string"}},"painPoints":{"type":"array","items":{"type":"string"}},"currentStack":{"type":"array","items":{"type":"string"}},"buyingTriggers":{"type":"array","items":{"type":"string"}},"objections":{"type":"array","items":{"type":"string"}}},"required":["goals","painPoints","currentStack","buyingTriggers","objections"]},"conversationPrompts":{"type":"array","items":{"type":"string"},"description":"Opening prompts the persona plays against each engine. Cleared when its details change; regenerate them with `promptsOnly` before the next run."},"enabled":{"type":"boolean","description":"Whether scheduled scans play this persona."},"archivedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"memories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["background","experience","preference","constraint"]},"content":{"type":"string"}},"required":["id","kind","content"]}}},"required":["id","name","role","company","summary","searchStyle","profile","conversationPrompts","enabled","archivedAt","createdAt","updatedAt","memories"]},"GeoPersonaResponse":{"type":"object","properties":{"persona":{"$ref":"#/components/schemas/GeoPersona"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["persona","organization"]},"PatchGeoPersonaRequest":{"type":"object","properties":{"enabled":{"type":"boolean"},"name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","minLength":1,"maxLength":200,"pattern":"^\\S+(?:\\s+\\S+)?$"},"company":{"type":"string","minLength":1,"maxLength":200},"summary":{"type":"string","minLength":1,"maxLength":800},"searchStyle":{"type":"string","minLength":1,"maxLength":800},"profile":{"type":"object","properties":{"goals":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":6},"painPoints":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":6},"currentStack":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":6},"buyingTriggers":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":6},"objections":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":6}},"description":"Lists to replace. Omitted lists keep their value."}}},"ArchiveGeoPersonaResponse":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","organization"]},"GeoPersonaResultsResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"scanId":{"type":"string"},"turn":{"type":"integer","description":"Conversation turn, starting at 1."},"engine":{"type":"string"},"prompt":{"type":"string"},"answer":{"type":"string"},"mentioned":{"type":"boolean"},"position":{"type":["number","null"]},"sentiment":{"type":["string","null"]},"excerpt":{"type":"string"},"searchQueries":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"},"domain":{"type":"string"}},"required":["title","url","domain"]}},"snapshotVersion":{"type":["string","null"],"description":"Hash of the persona context this answer was played with. Changes when the persona is edited."},"lastCheckedAt":{"type":"string"}},"required":["scanId","turn","engine","prompt","answer","mentioned","position","sentiment","excerpt","searchQueries","sources","snapshotVersion","lastCheckedAt"]}},"scans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"capturedAt":{"type":"string"}},"required":["id","capturedAt"]}},"selectedScanId":{"type":["string","null"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["results","scans","selectedScanId","organization"]},"GeoPersonaActivityResponse":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"personaId":{"type":"string"},"snapshotVersion":{"type":"string"},"day":{"type":"string"},"lastCheckedAt":{"type":"string"},"checks":{"type":"integer"},"mentions":{"type":"integer"}},"required":["personaId","snapshotVersion","day","lastCheckedAt","checks","mentions"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["from","to","points","organization"]},"RunGeoPersonaResponse":{"type":"object","properties":{"checks":{"type":"integer","description":"Answers recorded during this request by the API-based engines that responded."},"mentions":{"type":"integer"},"engines":{"type":"array","items":{"type":"string"}},"queuedScanId":{"type":["string","null"],"default":null,"description":"Scan that plays the persona in the tracked consumer apps in the background, or `null`. Poll `GET /v1/projects/{projectId}/geo/scans/{scanId}`."},"queuedEngines":{"type":"array","items":{"type":"string"},"default":[]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["checks","mentions","engines","organization"]},"GeoPersonaGenerationResponse":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/GeoPersonaGenerationJob"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["job","organization"]},"GeoPersonaGenerationJob":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed"]},"personaId":{"type":["string","null"]},"startedAt":{"type":"string"},"error":{"type":["string","null"]}},"required":["id","status","personaId","startedAt","error"],"description":"The project's latest generation job, or `null` when none ran recently."},"GenerateGeoPersonasRequest":{"type":"object","properties":{"personaId":{"type":"string","minLength":1,"description":"Regenerate this persona in place instead of creating a new set."},"brief":{"type":"string","minLength":1,"maxLength":2000,"description":"Describe one persona to add, such as 'a CFO at a 200-person logistics company'."},"promptsOnly":{"type":"boolean","enum":[true],"description":"With personaId, only rewrite its conversation prompts and keep its details."}}},"ListGeoCompetitorsResponse":{"type":"object","properties":{"competitors":{"type":"array","items":{"$ref":"#/components/schemas/GeoCompetitor"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["competitors","organization"]},"GeoCompetitor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":["string","null"]},"synonyms":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["direct","indirect"]},"color":{"type":["string","null"]}},"required":["id","name","domain","synonyms","kind","color"]},"PutGeoCompetitorRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"previousName":{"type":"string","minLength":1,"maxLength":128,"description":"Set to rename an existing competitor."},"domain":{"type":["string","null"],"maxLength":128},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":8},"kind":{"type":"string","enum":["direct","indirect"]},"color":{"type":["string","null"],"maxLength":128}},"required":["name","domain"]},"GeoCompetitorSuggestionsResponse":{"type":"object","properties":{"domain":{"type":"string"},"field":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":["string","null"]},"description":{"type":["string","null"]},"confidence":{"type":["string","null"],"enum":["high","medium",null]}},"required":["name","domain","description","confidence"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["domain","field","competitors","organization"]},"ImportGeoCompetitorsResponse":{"type":"object","properties":{"imported":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"issues":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer"},"message":{"type":"string"}},"required":["line","message"]}},"competitors":{"type":"array","items":{"$ref":"#/components/schemas/GeoCompetitor"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["imported","updated","skipped","issues","competitors","organization"]},"ImportGeoCompetitorsRequest":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"domain":{"type":["string","null"],"maxLength":128},"kind":{"type":"string","enum":["direct","indirect"]},"synonyms":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":8}},"required":["name"]},"minItems":1,"maxItems":2000},"csv":{"type":"string","minLength":1,"maxLength":1048576,"description":"Raw CSV text with a `name` column (optionally `domain`, `kind`, `synonyms`). Used when `rows` is omitted."}}},"CreateGeoScanResponse":{"type":"object","properties":{"scanId":{"type":"string"},"statusUrl":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["scanId","statusUrl","organization"]},"ListGeoScansResponse":{"type":"object","properties":{"scans":{"type":"array","items":{"$ref":"#/components/schemas/GeoScan"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"currentPage":{"type":"integer","minimum":1},"nextPage":{"type":["integer","null"],"minimum":1},"previousPage":{"type":["integer","null"],"minimum":1},"totalPages":{"type":"integer","minimum":1},"totalItems":{"type":"integer","minimum":0}},"required":["limit","currentPage","nextPage","previousPage","totalPages","totalItems"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["scans","pagination","organization"]},"GeoScan":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"status":{"type":"string","enum":["running","completed","failed"]},"startedAt":{"type":"string"},"finishedAt":{"type":["string","null"]},"createdAt":{"type":"string"},"summary":{"type":"object","properties":{"plannedChecks":{"type":["integer","null"],"minimum":0},"completedChecks":{"type":"integer","minimum":0},"mentionCount":{"type":"integer","minimum":0},"failedChecks":{"type":"integer","minimum":0},"engines":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"plannedChecks":{"type":["integer","null"],"minimum":0},"completedChecks":{"type":"integer","minimum":0},"mentionCount":{"type":"integer","minimum":0},"failedChecks":{"type":"integer","minimum":0}},"required":["engine","plannedChecks","completedChecks","mentionCount","failedChecks"]}}},"required":["plannedChecks","completedChecks","mentionCount","failedChecks","engines"]},"errorCode":{"type":["string","null"]},"errorMessage":{"type":["string","null"]},"failedStage":{"type":["string","null"],"enum":["handoff","execution","stale",null]},"retryable":{"type":["boolean","null"]}},"required":["id","projectId","status","startedAt","finishedAt","createdAt","summary","errorCode","errorMessage","failedStage","retryable"]},"GeoScanResponse":{"type":"object","properties":{"scan":{"$ref":"#/components/schemas/GeoScan"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["scan","organization"]},"GeoVisibilityOverviewResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"Whether the analytics backend is configured."},"engines":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"checks":{"type":"integer"},"mentions":{"type":"integer"},"mentionRate":{"type":"number"},"citations":{"type":"integer"},"visibility":{"type":"integer"},"visibilityRate":{"type":"number"},"avgPosition":{"type":["number","null"]},"lastCheckedAt":{"type":"string"}},"required":["engine","checks","mentions","mentionRate","citations","visibility","visibilityRate","avgPosition","lastCheckedAt"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","engines","organization"]},"GeoVisibilityTimeseriesResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"engine":{"type":"string"},"checks":{"type":"integer"},"mentions":{"type":"integer"},"citations":{"type":"integer"},"visibility":{"type":"integer"},"avgPosition":{"type":["number","null"]}},"required":["day","engine","checks","mentions","citations","visibility"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","points","organization"]},"GeoVisibilityPromptResultsResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"results":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string"},"engine":{"type":"string"},"prompt":{"type":"string"},"answer":{"type":"string"},"mentioned":{"type":"boolean"},"ownedSourceCited":{"type":"boolean"},"position":{"type":["integer","null"]},"sentiment":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"string"}},"excerpt":{"type":"string"},"searchQueries":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"},"domain":{"type":"string"}},"required":["title","url","domain"]}},"lastCheckedAt":{"type":"string"}},"required":["promptId","engine","prompt","answer","mentioned","ownedSourceCited","position","sentiment","competitors","excerpt","searchQueries","sources","lastCheckedAt"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","results","organization"]},"GeoVisibilityPromptResultSummariesResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"results":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string"},"engine":{"type":"string"},"prompt":{"type":"string"},"mentioned":{"type":"boolean"},"ownedSourceCited":{"type":"boolean"},"position":{"type":["integer","null"]},"sentiment":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"string"}},"lastCheckedAt":{"type":"string"},"checkId":{"type":"string"}},"required":["promptId","engine","prompt","mentioned","ownedSourceCited","position","sentiment","competitors","lastCheckedAt","checkId"]}},"nextCursor":{"type":["string","null"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","results","nextCursor","organization"]},"GeoVisibilityPromptResultDetailResponse":{"type":"object","properties":{"result":{"type":"object","properties":{"promptId":{"type":"string"},"engine":{"type":"string"},"prompt":{"type":"string"},"answer":{"type":"string"},"mentioned":{"type":"boolean"},"ownedSourceCited":{"type":"boolean"},"position":{"type":["integer","null"]},"sentiment":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"string"}},"excerpt":{"type":"string"},"searchQueries":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string"},"domain":{"type":"string"}},"required":["title","url","domain"]}},"lastCheckedAt":{"type":"string"},"finishReason":{"type":["string","null"]},"promptTokens":{"type":["integer","null"]},"outputTokens":{"type":["integer","null"]},"reasoningTokens":{"type":["integer","null"]},"truncated":{"type":["boolean","null"]}},"required":["promptId","engine","prompt","answer","mentioned","ownedSourceCited","position","sentiment","competitors","excerpt","searchQueries","sources","lastCheckedAt","finishReason","promptTokens","outputTokens","reasoningTokens","truncated"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["result","organization"]},"GeoVisibilityCompetitorShareResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"mentions":{"type":"integer"},"trend":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"value":{"type":"number"}},"required":["day","value"]}}},"required":["brand","mentions"]}},"timeseries":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"day":{"type":"string"},"mentions":{"type":"integer"}},"required":["brand","day","mentions"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","points","timeseries","organization"]},"GeoVisibilityLanguageShareResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"checks":{"type":"integer"},"mentions":{"type":"integer"},"mentionRate":{"type":"number"},"citations":{"type":"integer"},"visibility":{"type":"integer"},"visibilityRate":{"type":"number"},"avgPosition":{"type":["number","null"]},"trend":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"value":{"type":"number"}},"required":["day","value"]}}},"required":["language","checks","mentions","mentionRate","citations","visibility","visibilityRate","avgPosition"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","points","organization"]},"GeoVisibilityCompetitorDetailResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"points":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"mentions":{"type":"integer"},"checks":{"type":"integer"}},"required":["day","mentions","checks"]}},"prompts":{"type":"array","items":{"type":"object","properties":{"promptId":{"type":"string"},"prompt":{"type":"string"},"engine":{"type":"string"},"capturedAt":{"type":"string"},"mentioned":{"type":"boolean"},"position":{"type":["integer","null"]}},"required":["promptId","prompt","engine","capturedAt","mentioned","position"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","points","prompts","organization"]},"GeoChangesResponse":{"type":"object","properties":{"previousScan":{"type":["object","null"],"properties":{"id":{"type":"string"},"finishedAt":{"type":["string","null"]}},"required":["id","finishedAt"]},"currentScan":{"type":["object","null"],"properties":{"id":{"type":"string"},"finishedAt":{"type":["string","null"]}},"required":["id","finishedAt"]},"summary":{"type":"object","properties":{"gained":{"type":"integer"},"lost":{"type":"integer"},"positionImproved":{"type":"integer"},"positionDropped":{"type":"integer"},"citationsAdded":{"type":"integer"},"citationsRemoved":{"type":"integer"}},"required":["gained","lost","positionImproved","positionDropped","citationsAdded","citationsRemoved"]},"events":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["gained_mention","lost_mention","position_improved","position_dropped","competitor_displaced","citation_added","citation_removed","competitor_cited","new_engine"]},"promptId":{"type":"string"},"prompt":{"type":"string"},"engine":{"type":"string"},"previous":{"type":["object","null"],"properties":{"mentioned":{"type":"boolean"},"position":{"type":["number","null"]}},"required":["mentioned","position"]},"current":{"type":"object","properties":{"mentioned":{"type":"boolean"},"position":{"type":["number","null"]}},"required":["mentioned","position"]},"competitors":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}}},"required":["kind","promptId","prompt","engine","previous","current","competitors","domains"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["previousScan","currentScan","summary","events","organization"]},"GeoPromptHistoryResponse":{"type":"object","properties":{"configured":{"type":"boolean"},"promptId":{"type":"string"},"checks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"scanId":{"type":"string"},"engine":{"type":"string"},"mentioned":{"type":"boolean"},"ownedSourceCited":{"type":"boolean"},"position":{"type":["number","null"]},"sentiment":{"type":["string","null"]},"competitors":{"type":"array","items":{"type":"string"}},"language":{"type":"string"},"capturedAt":{"type":"string"}},"required":["id","scanId","engine","mentioned","position","sentiment","competitors","language","capturedAt"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","promptId","checks","organization"]},"GeoSentimentResponse":{"type":"object","properties":{"configured":{"type":"boolean","enum":[true]},"summary":{"type":"object","properties":{"totalChecks":{"type":"integer"},"mentions":{"type":"integer"},"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"},"lastCheckedAt":{"type":["string","null"]},"score":{"type":["number","null"]},"classifiedMentions":{"type":"integer"},"unknownMentions":{"type":"integer"},"notMentioned":{"type":"integer"},"positiveShare":{"type":["number","null"]},"neutralShare":{"type":["number","null"]},"negativeShare":{"type":["number","null"]},"classificationCoverage":{"type":["number","null"]}},"required":["totalChecks","mentions","positive","neutral","negative","lastCheckedAt","score","classifiedMentions","unknownMentions","notMentioned","positiveShare","neutralShare","negativeShare","classificationCoverage"]},"engines":{"type":"array","items":{"type":"object","properties":{"totalChecks":{"type":"integer"},"mentions":{"type":"integer"},"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"},"lastCheckedAt":{"type":["string","null"]},"score":{"type":["number","null"]},"classifiedMentions":{"type":"integer"},"unknownMentions":{"type":"integer"},"notMentioned":{"type":"integer"},"positiveShare":{"type":["number","null"]},"neutralShare":{"type":["number","null"]},"negativeShare":{"type":["number","null"]},"classificationCoverage":{"type":["number","null"]},"engine":{"type":"string"}},"required":["totalChecks","mentions","positive","neutral","negative","lastCheckedAt","score","classifiedMentions","unknownMentions","notMentioned","positiveShare","neutralShare","negativeShare","classificationCoverage","engine"]}},"points":{"type":"array","items":{"type":"object","properties":{"totalChecks":{"type":"integer"},"mentions":{"type":"integer"},"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"},"lastCheckedAt":{"type":["string","null"]},"score":{"type":["number","null"]},"classifiedMentions":{"type":"integer"},"unknownMentions":{"type":"integer"},"notMentioned":{"type":"integer"},"positiveShare":{"type":["number","null"]},"neutralShare":{"type":["number","null"]},"negativeShare":{"type":["number","null"]},"classificationCoverage":{"type":["number","null"]},"day":{"type":"string"}},"required":["totalChecks","mentions","positive","neutral","negative","lastCheckedAt","score","classifiedMentions","unknownMentions","notMentioned","positiveShare","neutralShare","negativeShare","classificationCoverage","day"]}},"comparison":{"type":"object","properties":{"current":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"previous":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"summary":{"type":"object","properties":{"totalChecks":{"type":"integer"},"mentions":{"type":"integer"},"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"},"lastCheckedAt":{"type":["string","null"]},"score":{"type":["number","null"]},"classifiedMentions":{"type":"integer"},"unknownMentions":{"type":"integer"},"notMentioned":{"type":"integer"},"positiveShare":{"type":["number","null"]},"neutralShare":{"type":["number","null"]},"negativeShare":{"type":["number","null"]},"classificationCoverage":{"type":["number","null"]}},"required":["totalChecks","mentions","positive","neutral","negative","lastCheckedAt","score","classifiedMentions","unknownMentions","notMentioned","positiveShare","neutralShare","negativeShare","classificationCoverage"]},"points":{"type":"array","items":{"type":"object","properties":{"totalChecks":{"type":"integer"},"mentions":{"type":"integer"},"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"},"lastCheckedAt":{"type":["string","null"]},"score":{"type":["number","null"]},"classifiedMentions":{"type":"integer"},"unknownMentions":{"type":"integer"},"notMentioned":{"type":"integer"},"positiveShare":{"type":["number","null"]},"neutralShare":{"type":["number","null"]},"negativeShare":{"type":["number","null"]},"classificationCoverage":{"type":["number","null"]},"day":{"type":"string"}},"required":["totalChecks","mentions","positive","neutral","negative","lastCheckedAt","score","classifiedMentions","unknownMentions","notMentioned","positiveShare","neutralShare","negativeShare","classificationCoverage","day"]}},"delta":{"type":["number","null"]}},"required":["current","previous","summary","points","delta"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","summary","engines","points","organization"]},"GeoSentimentAnalysisResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ready","pending","stale","failed","unavailable"]},"result":{"type":["object","null"],"properties":{"fingerprint":{"type":"string"},"generatedAt":{"type":"string"},"sampled":{"type":"integer"},"eligible":{"type":"integer"},"themes":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"polarity":{"type":"string","enum":["positive","negative"]},"claims":{"type":"array","items":{"type":"object","properties":{"statement":{"type":"string"},"evidence":{"type":"array","items":{"type":"object","properties":{"checkId":{"type":"string"},"quote":{"type":"string"},"prompt":{"type":"string"},"engine":{"type":"string"},"capturedAt":{"type":"string"}},"required":["checkId","quote","prompt","engine","capturedAt"]}}},"required":["statement","evidence"]}},"evidence":{"type":"array","items":{"type":"object","properties":{"checkId":{"type":"string"},"quote":{"type":"string"},"prompt":{"type":"string"},"engine":{"type":"string"},"capturedAt":{"type":"string"}},"required":["checkId","quote","prompt","engine","capturedAt"]}}},"required":["title","polarity","claims","evidence"]}}},"required":["fingerprint","generatedAt","sampled","eligible","themes"]},"message":{"type":["string","null"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["status","result","message","organization"]},"GeoSentimentEvidenceResponse":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"scanId":{"type":"string"},"promptId":{"type":"string"},"prompt":{"type":"string"},"engine":{"type":"string"},"language":{"type":"string"},"capturedAt":{"type":"string"},"answer":{"type":"string"},"excerpt":{"type":"string"}},"required":["id","scanId","promptId","prompt","engine","language","capturedAt","answer","excerpt"]}},"nextCursor":{"type":["string","null"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["items","nextCursor","organization"]},"GeoShelfListResponse":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"url":{"type":"string","maxLength":2048,"format":"uri"},"domain":{"type":"string","minLength":1},"title":{"type":["string","null"],"maxLength":200},"kind":{"type":"string","enum":["listicle","review_site","community","news","docs","video","other"]},"ownership":{"type":"string","enum":["third_party","own","competitor"]},"origin":{"type":"string","enum":["scan","manual"]},"fetchStatus":{"type":"string","enum":["pending","ok","blocked","failed"]},"lastFetchedAt":{"type":["string","null"],"format":"date-time"},"citations":{"type":"object","properties":{"windowCount":{"type":"integer","minimum":0},"totalCount":{"type":"integer","minimum":0},"promptCount":{"type":"integer","minimum":0},"engines":{"type":"array","items":{"type":"string","minLength":1}},"firstCitedAt":{"type":["string","null"],"format":"date-time"},"lastCitedAt":{"type":["string","null"],"format":"date-time"}},"required":["windowCount","totalCount","promptCount","engines","firstCitedAt","lastCitedAt"]},"placements":{"type":"array","items":{"type":"object","properties":{"competitorId":{"type":["string","null"],"minLength":1},"brandName":{"type":"string","minLength":1},"brandDomain":{"type":["string","null"]},"status":{"type":"string","enum":["present","absent","unknown"]},"position":{"type":["integer","null"],"exclusiveMinimum":0},"hasLink":{"type":"boolean"},"evidence":{"type":"string","enum":["fetch","manual"]},"excerpt":{"type":["string","null"]},"checkedAt":{"type":"string","format":"date-time"}},"required":["competitorId","brandName","brandDomain","status","position","hasLink","evidence","excerpt","checkedAt"]}},"opportunity":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["open","in_progress","won","lost","dismissed"]},"priority":{"type":["string","null"],"enum":["low","medium","high",null]},"assigneeMemberId":{"type":["string","null"],"minLength":1},"pocMemberId":{"type":["string","null"],"minLength":1},"notes":{"type":["string","null"],"maxLength":2000},"dueAt":{"type":["string","null"],"format":"date-time"},"id":{"type":"string","minLength":1},"createdByUserId":{"type":["string","null"],"minLength":1},"resolvedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["status","priority","assigneeMemberId","pocMemberId","notes","dueAt","id","createdByUserId","resolvedAt","createdAt","updatedAt"]},"createdByUserId":{"type":["string","null"],"minLength":1},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","url","domain","title","kind","ownership","origin","fetchStatus","lastFetchedAt","citations","placements","opportunity","createdByUserId","createdAt","updatedAt"]}},"nextOffset":{"type":["integer","null"],"minimum":0},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["sources","nextOffset","organization"]},"GeoContentGapsResponse":{"type":"object","properties":{"promptGaps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"prompt":{"type":"string"},"title":{"type":["string","null"]},"engines":{"type":"array","items":{"type":"string"}},"mentionedEngines":{"type":"array","items":{"type":"string"}},"competitors":{"type":"array","items":{"type":"string"}},"discoveredCompetitors":{"type":"array","items":{"type":"string"}},"searchQueries":{"type":"array","items":{"type":"string"},"description":"Web searches AI engines ran while answering this prompt."},"ownMentionRate":{"type":"number"},"engineCoverage":{"type":"number"},"opportunity":{"type":"number"},"won":{"type":"boolean"},"brief":{"type":["object","null"],"properties":{"briefId":{"type":"string"},"status":{"type":"string","enum":["draft","approved","writing","completed","failed"]},"postId":{"type":["string","null"]},"workingTitle":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"baseline":{"type":["object","null"],"properties":{"mentionedEngines":{"type":"number"},"totalEngines":{"type":"number"}},"required":["mentionedEngines","totalEngines"]},"rescanned":{"type":"boolean"}},"required":["briefId","status","postId","workingTitle","publishedAt","baseline","rescanned"]}},"required":["id","prompt","title","engines","mentionedEngines","competitors","discoveredCompetitors","searchQueries","ownMentionRate","engineCoverage","opportunity","won","brief"]}},"searchGaps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"prompt":{"type":"string"},"title":{"type":["string","null"]},"impressions":{"type":["number","null"]},"clicks":{"type":["number","null"]},"position":{"type":["number","null"]},"queries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"clicks":{"type":"number"},"impressions":{"type":"number"},"position":{"type":"number"},"page":{"type":"string","description":"Page Google showed most for this query."},"pagePosition":{"type":"number","description":"Google position of that page for this query."},"pageImpressions":{"type":"number","description":"Impressions of that page for this query."}},"required":["query","clicks","impressions","position"]}},"brief":{"type":["object","null"],"properties":{"briefId":{"type":"string"},"status":{"type":"string","enum":["draft","approved","writing","completed","failed"]},"postId":{"type":["string","null"]},"workingTitle":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"baseline":{"type":["object","null"],"properties":{"mentionedEngines":{"type":"number"},"totalEngines":{"type":"number"}},"required":["mentionedEngines","totalEngines"]},"rescanned":{"type":"boolean"}},"required":["briefId","status","postId","workingTitle","publishedAt","baseline","rescanned"]},"recommendation":{"type":"object","properties":{"action":{"type":"string","enum":["create","update","merge","ignore"],"description":"What to do with this query cluster: create a new page, update the page Google already ranks or the strongest existing page, merge overlapping pages, or ignore thin demand."},"reason":{"type":"string"},"targets":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["page","post"]},"id":{"type":"string"},"url":{"type":["string","null"]},"title":{"type":"string"},"score":{"type":"number"},"googlePosition":{"type":"number","description":"Google position of the gap's queries on this page, when Search Console shows it already ranks there."}},"required":["kind","id","url","title","score"]}}},"required":["action","reason","targets"]}},"required":["id","prompt","title","impressions","clicks","position","queries","brief","recommendation"]}},"aiSearchGaps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"query":{"type":"string"},"variants":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"string"}},"engines":{"type":"array","items":{"type":"string"}},"searches":{"type":"number","description":"Scan answers in which an engine ran this web search without mentioning the brand or citing its site."},"ownMentionRate":{"type":"number"},"competitors":{"type":"array","items":{"type":"string"}},"discoveredCompetitors":{"type":"array","items":{"type":"string"}},"opportunity":{"type":"number"},"brief":{"type":["object","null"],"properties":{"briefId":{"type":"string"},"status":{"type":"string","enum":["draft","approved","writing","completed","failed"]},"postId":{"type":["string","null"]},"workingTitle":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"baseline":{"type":["object","null"],"properties":{"mentionedEngines":{"type":"number"},"totalEngines":{"type":"number"}},"required":["mentionedEngines","totalEngines"]},"rescanned":{"type":"boolean"}},"required":["briefId","status","postId","workingTitle","publishedAt","baseline","rescanned"]}},"required":["id","query","variants","prompts","engines","searches","ownMentionRate","competitors","discoveredCompetitors","opportunity","brief"]},"description":"Web searches AI engines ran in scan answers without mentioning the brand or citing its site."},"hasScanData":{"type":"boolean","description":"False until the project has at least one scan result."},"snapshotReady":{"type":"boolean","description":"False while the project's content gaps snapshot is being prepared."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["promptGaps","searchGaps","aiSearchGaps","hasScanData","snapshotReady","organization"]},"UpdateGeoContentGapResponse":{"type":"object","properties":{"promptId":{"type":"string"},"ignored":{"type":"boolean"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["promptId","ignored","organization"]},"UpdateGeoContentGapRequest":{"type":"object","properties":{"ignored":{"type":"boolean","description":"true hides the prompt gap from content gaps and brief planning; false brings it back."}},"required":["ignored"]},"ListGeoContentBriefsResponse":{"type":"object","properties":{"briefs":{"type":"array","items":{"$ref":"#/components/schemas/GeoContentBriefSummary"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["briefs","organization"]},"GeoContentBriefSummary":{"type":"object","properties":{"id":{"type":"string"},"topic":{"type":"string"},"workingTitle":{"type":"string"},"status":{"type":"string","enum":["draft","approved","writing","completed","failed"]},"postId":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","topic","workingTitle","status","postId","createdAt"]},"GeoContentBriefResponse":{"type":"object","properties":{"brief":{"$ref":"#/components/schemas/GeoContentBriefDetail"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["brief","organization"]},"GeoContentBriefDetail":{"type":"object","properties":{"id":{"type":"string"},"topic":{"type":"string"},"brief":{"$ref":"#/components/schemas/GeoContentBriefDocument"},"status":{"type":"string","enum":["draft","approved","writing","completed","failed"]},"autoApproved":{"type":"boolean"},"runId":{"type":["string","null"]},"postId":{"type":["string","null"]},"humanized":{"type":"boolean"},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","topic","brief","status","autoApproved","runId","postId","humanized","error","createdAt","updatedAt","completedAt"]},"GeoContentBriefDocument":{"type":"object","properties":{"targetPrompt":{"type":"string"},"intent":{"type":"string"},"contentSubtype":{"type":"string","enum":["guide","comparison","listicle","how-to","faq","alternatives"]},"workingTitle":{"type":"string"},"audience":{"type":"string"},"jobToBeDone":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"heading":{"type":"string"},"goal":{"type":"string"},"claims":{"type":"array","items":{"type":"string"}}},"required":["heading","goal","claims"]}},"questionsToAnswer":{"type":"array","items":{"type":"string"}},"internalLinks":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"anchor":{"type":"string"},"why":{"type":"string"}},"required":["url","anchor","why"]}},"acceptanceChecklist":{"type":"array","items":{"type":"string"}},"recommendedAngle":{"type":"string"},"competitorsToCounter":{"type":"array","items":{"type":"string"}},"sourcesToReference":{"type":"array","items":{"type":"string"}},"missingCoverage":{"type":"array","items":{"type":"string"}},"baseline":{"type":["object","null"],"properties":{"sourcePromptId":{"type":"string"},"mentionedEngines":{"type":"number"},"totalEngines":{"type":"number"},"engines":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"mentioned":{"type":"boolean"},"position":{"type":["number","null"]}},"required":["engine","mentioned","position"]}},"competitorMentions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"engines":{"type":"number"}},"required":["name","engines"]}},"citedDomains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"engines":{"type":"number"}},"required":["domain","engines"]}},"capturedAt":{"type":["string","null"]}},"required":["sourcePromptId","mentionedEngines","totalEngines","engines","competitorMentions","citedDomains","capturedAt"]}},"required":["targetPrompt","intent","contentSubtype","workingTitle","audience","jobToBeDone","sections","questionsToAnswer","internalLinks","acceptanceChecklist"]},"UpdateGeoContentBriefRequest":{"type":"object","properties":{"expectedUpdatedAt":{"type":"string","format":"date-time","description":"The brief's updatedAt from your last read. When set, the update fails with 409 if the brief changed since. Omit to overwrite the latest version."},"workingTitle":{"type":"string","minLength":1,"maxLength":120,"pattern":"^[^\\r\\n]*$"},"targetPrompt":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"intent":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"audience":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"jobToBeDone":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"sections":{"type":"array","items":{"type":"object","properties":{"heading":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"goal":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"claims":{"type":"array","items":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"maxItems":5}},"required":["heading","goal","claims"]},"minItems":3,"maxItems":8,"description":"The outline. Replaces every section; send the full list in order."},"questionsToAnswer":{"type":"array","items":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"maxItems":8,"description":"FAQ questions. Replaces the whole list."},"internalLinks":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"anchor":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"why":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"}},"required":["url","anchor","why"]},"maxItems":6,"description":"Replaces the whole list."},"acceptanceChecklist":{"type":"array","items":{"type":"string","minLength":1,"pattern":"^[^\\r\\n]*$"},"maxItems":8,"description":"Replaces the whole list."}}},"PlanGeoContentBriefResponse":{"type":"object","properties":{"briefId":{"type":"string"},"brief":{"$ref":"#/components/schemas/GeoContentBriefDocument"},"status":{"type":"string","enum":["draft","approved","writing","completed","failed"]},"runId":{"type":["string","null"]},"postId":{"type":["string","null"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["briefId","brief","status","runId","postId","organization"]},"PlanGeoContentBriefRequest":{"type":"object","properties":{"topic":{"type":"string","minLength":3,"maxLength":200,"description":"What the article should target. Replaced by the source prompt when sourceKind is gap, prompt or search_console."},"autoApprove":{"type":"boolean","default":false,"description":"Start the writer immediately instead of leaving the brief in draft."},"contentSubtype":{"type":"string","enum":["guide","comparison","listicle","how-to","faq","alternatives"]},"brandVoiceIds":{"type":"array","items":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"maxItems":8,"description":"Only the first entry is used; it overrides the project's brand identity."},"competitorIds":{"type":"array","items":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"maxItems":2000},"sitemapId":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"sourceKind":{"type":"string","enum":["manual","gap","prompt","search_console","ai_search"]},"sourceId":{"type":"string","minLength":1,"description":"Gap, prompt or search-console suggestion id. An open brief for the same source is reused instead of planning a new one."},"existingPageUrl":{"type":"string","maxLength":2048,"format":"uri","description":"Existing page the article should refresh instead of creating a competing page."}},"required":["topic"]},"ApproveGeoContentBriefResponse":{"type":"object","properties":{"runId":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["runId","organization"]},"GeoAgentReadinessResponse":{"type":"object","properties":{"targetUrl":{"type":"string"},"report":{"$ref":"#/components/schemas/GeoAgentReadinessReport"},"scan":{"allOf":[{"$ref":"#/components/schemas/GeoAgentReadinessReport"},{"description":"Latest run newer than the completed report, if any."}]},"history":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"score":{"type":["number","null"]},"failedCount":{"type":"integer"},"partialCount":{"type":"integer"},"scannedAt":{"type":"string"}},"required":["id","score","failedCount","partialCount","scannedAt"]},"description":"Completed scans, oldest first."},"comparison":{"type":["object","null"],"properties":{"previousScore":{"type":["number","null"]},"previousScannedAt":{"type":"string"},"resolved":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["essential","recommended","bonus"]},"previousResult":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the previous scan; null when the check passed."},"result":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the latest scan; null when the check passes now."}},"required":["id","name","tier","previousResult","result"]}},"added":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["essential","recommended","bonus"]},"previousResult":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the previous scan; null when the check passed."},"result":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the latest scan; null when the check passes now."}},"required":["id","name","tier","previousResult","result"]}},"improved":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["essential","recommended","bonus"]},"previousResult":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the previous scan; null when the check passed."},"result":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the latest scan; null when the check passes now."}},"required":["id","name","tier","previousResult","result"]},"description":"Checks that went from failed to partial."},"worsened":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["essential","recommended","bonus"]},"previousResult":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the previous scan; null when the check passed."},"result":{"type":["string","null"],"enum":["failed","partial",null],"description":"Result on the latest scan; null when the check passes now."}},"required":["id","name","tier","previousResult","result"]},"description":"Checks that went from partial to failed."}},"required":["previousScore","previousScannedAt","resolved","added","improved","worsened"],"description":"Checks that changed between the latest completed scan and the one before it. Null until there are two completed scans."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["targetUrl","report","scan","history","comparison","organization"]},"GeoAgentReadinessReport":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","completed","failed"]},"targetUrl":{"type":"string"},"score":{"type":["number","null"]},"scoreLabel":{"type":["string","null"]},"scoreBreakdown":{"type":["object","null"],"properties":{"essential":{"type":"object","properties":{"earned":{"type":"number"},"available":{"type":"number"},"passing":{"type":"number"},"total":{"type":"number"}},"required":["earned","available","passing","total"]},"recommended":{"type":"object","properties":{"earned":{"type":"number"},"available":{"type":"number"},"passing":{"type":"number"},"total":{"type":"number"}},"required":["earned","available","passing","total"]},"bonus":{"type":"object","properties":{"points":{"type":"number"},"positiveSignals":{"type":"number"}},"required":["points","positiveSignals"]}},"required":["essential","recommended","bonus"]},"issues":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string","enum":["essential","recommended","bonus"]},"result":{"type":"string","enum":["failed","partial"]},"details":{"type":["string","null"]},"recommendation":{"type":["string","null"]}},"required":["id","name","tier","result","details","recommendation"]}},"eligibleChecks":{"type":["integer","null"]},"errorMessage":{"type":["string","null"]},"scannedAt":{"type":["string","null"]},"createdAt":{"type":"string"}},"required":["id","status","targetUrl","score","scoreLabel","scoreBreakdown","issues","eligibleChecks","errorMessage","scannedAt","createdAt"],"description":"Latest completed report, if any."},"GeoAgentReadinessScanResponse":{"type":"object","properties":{"reportId":{"type":"string"},"alreadyRunning":{"type":"boolean","description":"True when an in-flight scan for the same URL was reused instead of starting a new one."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["reportId","alreadyRunning","organization"]},"GeoTrafficOverviewResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"False when the traffic backend is not configured for this deployment; the payload is then empty rather than an error."},"totals":{"type":"object","properties":{"crawler":{"type":"integer"},"cited":{"type":"integer"},"aiReferral":{"type":"integer"},"conversions":{"type":["integer","null"],"description":"AI referral visits that reached a configured conversion path. Null when no conversion paths are set."}},"required":["crawler","cited","aiReferral","conversions"]},"previousConversions":{"type":["integer","null"],"description":"Conversions in the previous window of the same length. Null when no conversion paths are set or no comparison data exists."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"visitorType":{"type":"string","enum":["crawler","ai_referral","human","unknown"]},"agent":{"type":"string"},"category":{"type":"string"},"confidence":{"type":"string"},"visits":{"type":"integer"},"previousVisits":{"type":"integer"},"markdownVisits":{"type":"integer"},"previousMarkdownVisits":{"type":"integer"},"paths":{"type":"integer"},"previousPaths":{"type":"integer"},"lastSeenAt":{"type":"string"}},"required":["source","visitorType","agent","category","confidence","visits","markdownVisits","paths","lastSeenAt"]}},"points":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"visitorType":{"type":"string","enum":["crawler","ai_referral","human","unknown"]},"source":{"type":"string"},"visits":{"type":"integer"}},"required":["day","visitorType","source","visits"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","totals","previousConversions","sources","points","organization"]},"GeoTrafficLogResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"False when the traffic backend is not configured for this deployment; the payload is then empty rather than an error."},"log":{"type":"array","items":{"type":"object","properties":{"capturedAt":{"type":"string"},"visitorType":{"type":"string","enum":["crawler","ai_referral","human","unknown"]},"source":{"type":"string"},"agent":{"type":"string"},"category":{"type":"string"},"confidence":{"type":"string"},"path":{"type":"string"},"host":{"type":"string"},"country":{"type":"string"},"ua":{"type":"string"},"journeyId":{"type":"string"},"wantsMarkdown":{"type":"boolean"}},"required":["capturedAt","visitorType","source","agent","category","confidence","path","host","country","ua","journeyId","wantsMarkdown"]}},"total":{"type":"integer"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","log","total","organization"]},"GeoTrafficJourneysResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"False when the traffic backend is not configured for this deployment; the payload is then empty rather than an error."},"journeys":{"type":"array","items":{"type":"object","properties":{"journeyId":{"type":"string"},"source":{"type":"string"},"visitorType":{"type":"string","enum":["crawler","ai_referral","human","unknown"]},"pages":{"type":"integer"},"distinctPaths":{"type":"integer"},"firstSeenAt":{"type":"string"},"lastSeenAt":{"type":"string"},"entryPath":{"type":"string"},"samplePaths":{"type":"array","items":{"type":"string"}}},"required":["journeyId","source","visitorType","pages","distinctPaths","firstSeenAt","lastSeenAt","entryPath","samplePaths"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","journeys","organization"]},"GeoJourneyDetailResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"False when the traffic backend is not configured for this deployment; the payload is then empty rather than an error."},"events":{"type":"array","items":{"type":"object","properties":{"capturedAt":{"type":"string"},"path":{"type":"string"},"host":{"type":"string"},"method":{"type":"string"},"referer":{"type":"string"},"country":{"type":"string"},"agent":{"type":"string"},"category":{"type":"string"}},"required":["capturedAt","path","host","method","referer","country","agent","category"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","events","organization"]},"GeoTrafficPagesResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"False when the traffic backend is not configured for this deployment; the payload is then empty rather than an error."},"pages":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"host":{"type":"string"},"source":{"type":"string"},"visitorType":{"type":"string","enum":["crawler","ai_referral","human","unknown"]},"visits":{"type":"integer"},"previousVisits":{"type":"integer"},"lastSeenAt":{"type":"string"}},"required":["path","host","source","visitorType","visits","lastSeenAt"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","pages","organization"]},"GeoMcpAnalyticsResponse":{"type":"object","properties":{"configured":{"type":"boolean","description":"False when the traffic backend is not configured for this deployment; the payload is then empty rather than an error."},"server":{"type":["object","null"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"protocolVersion":{"type":"string"}},"required":["name","version","protocolVersion"],"description":"Server info from the newest event. Null before any."},"totals":{"type":"object","properties":{"requests":{"type":"integer"},"previousRequests":{"type":"integer"},"toolCalls":{"type":"integer"},"previousToolCalls":{"type":"integer"},"errors":{"type":"integer"},"previousErrors":{"type":"integer"},"sessions":{"type":"integer"},"previousSessions":{"type":"integer"},"users":{"type":"integer"},"previousUsers":{"type":"integer"},"p95Ms":{"type":"integer"},"previousP95Ms":{"type":"integer"}},"required":["requests","previousRequests","toolCalls","previousToolCalls","errors","previousErrors","sessions","previousSessions","users","previousUsers","p95Ms","previousP95Ms"]},"daily":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"toolsCall":{"type":"integer"},"resourcesRead":{"type":"integer"},"promptsGet":{"type":"integer"},"other":{"type":"integer"},"errors":{"type":"integer"}},"required":["day","toolsCall","resourcesRead","promptsGet","other","errors"]}},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"calls":{"type":"integer"},"errors":{"type":"integer"},"users":{"type":"integer"},"avgResponseBytes":{"type":"integer"},"p50Ms":{"type":"integer"},"p95Ms":{"type":"integer"},"uiResource":{"type":"string"}},"required":["name","description","calls","errors","users","avgResponseBytes","p50Ms","p95Ms","uiResource"]}},"clients":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"sessions":{"type":"integer"},"requests":{"type":"integer"},"errors":{"type":"integer"},"lastSeenAt":{"type":"string"}},"required":["name","sessions","requests","errors","lastSeenAt"]}},"errorRequests":{"type":"array","items":{"type":"object","properties":{"capturedAt":{"type":"string"},"clientName":{"type":"string"},"clientVersion":{"type":"string"},"method":{"type":"string"},"target":{"type":"string"},"status":{"type":"string","enum":["ok","tool_error","rpc_error"]},"errorCode":{"type":"integer"},"errorMessage":{"type":"string"},"durationMs":{"type":"integer"},"model":{"type":"string"}},"required":["capturedAt","clientName","clientVersion","method","target","status","errorCode","errorMessage","durationMs","model"]},"description":"Most recent failed requests, newest first."},"models":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"sessions":{"type":"integer"},"calls":{"type":"integer"},"errors":{"type":"integer"}},"required":["name","sessions","calls","errors"]}},"intents":{"type":"array","items":{"type":"object","properties":{"intent":{"type":"string"},"tool":{"type":"string"},"calls":{"type":"integer"},"errors":{"type":"integer"}},"required":["intent","tool","calls","errors"]}},"elicitations":{"type":"array","items":{"type":"object","properties":{"method":{"type":"string"},"tool":{"type":"string"},"requests":{"type":"integer"},"accepted":{"type":"integer"},"declined":{"type":"integer"},"cancelled":{"type":"integer"},"errors":{"type":"integer"}},"required":["method","tool","requests","accepted","declined","cancelled","errors"]}},"uiRenders":{"type":"array","items":{"type":"object","properties":{"resource":{"type":"string"},"tools":{"type":"array","items":{"type":"string"}},"renders":{"type":"integer"},"sessions":{"type":"integer"},"errors":{"type":"integer"}},"required":["resource","tools","renders","sessions","errors"]}},"catalog":{"type":["object","null"],"properties":{"listedAt":{"type":"string"},"unusedTools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name","description"]}}},"required":["listedAt","unusedTools"],"description":"Tools from the latest tools/list that were never called in the window. Null before a listing is seen."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["configured","server","totals","daily","tools","clients","errorRequests","models","intents","elicitations","uiRenders","catalog","organization"]},"GeoMcpToolDetailResponse":{"type":"object","properties":{"before":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string"},"calls":{"type":"integer"},"afterFailure":{"type":"integer"}},"required":["tool","calls","afterFailure"]},"description":"Tools called right before this one in the same session."},"after":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string"},"calls":{"type":"integer"},"afterFailure":{"type":"integer"}},"required":["tool","calls","afterFailure"]},"description":"Tools called right after this one in the same session."},"failures":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string"},"clientName":{"type":"string"},"status":{"type":"string","enum":["ok","tool_error","rpc_error"]},"errorCode":{"type":"integer"},"calls":{"type":"integer"},"lastSeenAt":{"type":"string"}},"required":["message","clientName","status","errorCode","calls","lastSeenAt"]},"description":"Failures grouped by error message."},"intents":{"type":"array","items":{"type":"object","properties":{"intent":{"type":"string"},"tool":{"type":"string"},"calls":{"type":"integer"},"errors":{"type":"integer"}},"required":["intent","tool","calls","errors"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["before","after","failures","intents","organization"]},"GeoIngestSetupResponse":{"type":"object","properties":{"ingestUrl":{"type":"string","description":"Endpoint the tracking snippet posts events to."},"snippet":{"type":"string","description":"Install snippet for the default framework (Next.js)."},"snippets":{"type":"object","properties":{"next":{"type":"string"},"nuxt":{"type":"string"},"netlify":{"type":"string"},"tanstack":{"type":"string"},"astro":{"type":"string"},"sveltekit":{"type":"string"},"reactRouter":{"type":"string"}},"required":["next","nuxt","netlify","tanstack","astro","sveltekit","reactRouter"]},"drainUrls":{"type":"object","properties":{"vercel":{"type":"string"},"cloudflare":{"type":"string"}},"required":["vercel","cloudflare"],"description":"Endpoints a Vercel log drain or Cloudflare Logpush job posts request logs to, authenticated with the tracking token."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["ingestUrl","snippet","snippets","drainUrls","organization"]},"GeoIngestTokenResponse":{"type":"object","properties":{"ingestUrl":{"type":"string","description":"Endpoint the tracking snippet posts events to."},"snippet":{"type":"string","description":"Install snippet for the default framework (Next.js)."},"snippets":{"type":"object","properties":{"next":{"type":"string"},"nuxt":{"type":"string"},"netlify":{"type":"string"},"tanstack":{"type":"string"},"astro":{"type":"string"},"sveltekit":{"type":"string"},"reactRouter":{"type":"string"}},"required":["next","nuxt","netlify","tanstack","astro","sveltekit","reactRouter"]},"drainUrls":{"type":"object","properties":{"vercel":{"type":"string"},"cloudflare":{"type":"string"}},"required":["vercel","cloudflare"],"description":"Endpoints a Vercel log drain or Cloudflare Logpush job posts request logs to, authenticated with the tracking token."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"token":{"type":"string","description":"Tracking token. Shown once per request; rotating invalidates every previously issued token."}},"required":["ingestUrl","snippet","snippets","drainUrls","organization","token"]},"CreateAgentSessionResponse":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"sessionId":{"type":"string"}},"required":["ok","sessionId"]},"CreateAgentSessionRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":200000,"description":"The first user message of the session."}},"required":["message"]},"SendAgentMessageRequest":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":200000,"description":"The next user message. Omit when only answering a pending input request."},"inputResponses":{"type":"array","items":{"type":"object","properties":{"requestId":{"type":"string","minLength":1},"optionId":{"type":"string","minLength":1,"description":"The chosen option id from the input.requested event, e.g. \"approve\" or \"deny\"."}},"required":["requestId","optionId"]},"description":"Answers to pending input.requested events (tool approvals, questions) from the event stream."}}},"ListAgentChatsResponse":{"type":"object","properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/AgentSessionSummary"}}},"required":["sessions"]},"AgentSessionSummary":{"type":"object","properties":{"sessionId":{"type":"string"},"chatId":{"type":["string","null"]},"surface":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["sessionId","chatId","surface","status","createdAt","updatedAt"]}}},"paths":{"/v1/status":{"get":{"tags":["Discovery"],"operationId":"getPublicApiStatus","summary":"Check public API reachability","security":[],"responses":{"200":{"description":"Public reachability and authentication discovery metadata for agents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicStatusResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 120 requests per 1 minute per IP address.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/v1/posts":{"get":{"tags":["Content"],"operationId":"listPosts","summary":"List posts","description":"Returns posts for the organization the API key belongs to, newest first by default. Only published posts are included unless you pass status=draft,published. Blog posts and changelogs include a metadata object with cover image, tags, excerpt, authors, featured, noindex, hidden and displayDate; it is null for other content types.","parameters":[{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort by creation date","example":"desc"},"required":false,"description":"Sort by creation date","name":"sort","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":10,"description":"Items per page","example":10},"required":false,"description":"Items per page","name":"limit","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number","example":1},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"string","description":"Filter by status using a comma-separated list."},"required":false,"description":"Filter by status using a comma-separated list.","name":"status","in":"query"},{"schema":{"type":"string","description":"Filter by content type using a comma-separated list."},"required":false,"description":"Filter by content type using a comma-separated list.","name":"contentType","in":"query"},{"schema":{"type":"string","description":"Filter by brand identity ID using a comma-separated list."},"required":false,"description":"Filter by brand identity ID using a comma-separated list.","name":"brandIdentityId","in":"query"}],"responses":{"200":{"description":"Posts fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"posts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":["string","null"]},"content":{"type":"string","description":"Rendered HTML for text posts. For image posts, this is the public CDN URL of the rendered image."},"htmlUrl":{"type":["string","null"],"description":"Public CDN URL of the generated HTML artifact for image posts. Null for non-image posts."},"markdown":{"type":["string","null"],"description":"Markdown source for text posts. Null for image posts."},"rawHtml":{"type":["string","null"],"description":"Legacy inline generated HTML for image posts. New generated image HTML is stored as htmlUrl. Null for non-image posts."},"recommendations":{"type":["string","null"]},"contentType":{"type":"string","enum":["changelog","linkedin_post","twitter_post","blog_post","investor_update","image"]},"sourceMetadata":{},"metadata":{"type":["object","null"],"properties":{"coverImage":{"type":["object","null"],"properties":{"url":{"type":"string","description":"Absolute https URL, or a path to an image uploaded in Notra (starting with /api/uploads/).","example":"https://cdn.example.com/covers/ship-notes.png"},"alt":{"type":"string","description":"Alt text. Empty string when none is set.","example":"Screenshot of the new editor"}},"required":["url","alt"],"description":"Cover image shown on post cards and social previews."},"tags":{"type":"array","items":{"type":"string"},"example":["editor","performance"]},"excerpt":{"type":["string","null"],"description":"Summary shown on post cards and in meta descriptions. Null means it is derived from the first paragraph.","example":"The editor now opens twice as fast on long posts."},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"auth_8f2kq1"},"slug":{"type":"string","description":"Stable author handle; hosted sites list the author's posts at /author/{slug}.","example":"jane-doe"},"name":{"type":"string","example":"Jane Doe"},"title":{"type":["string","null"],"example":"Head of Product"},"avatarUrl":{"type":["string","null"],"example":"https://cdn.example.com/avatars/jane.png"},"url":{"type":["string","null"],"description":"Author's website.","example":"https://janedoe.dev"},"x":{"type":["string","null"],"example":"https://x.com/janedoe"},"linkedin":{"type":["string","null"]},"github":{"type":["string","null"]},"youtube":{"type":["string","null"]},"bluesky":{"type":["string","null"]},"mastodon":{"type":["string","null"]},"threads":{"type":["string","null"]},"instagram":{"type":["string","null"]}},"required":["id","slug","name","title","avatarUrl","url","x","linkedin","github","youtube","bluesky","mastodon","threads","instagram"]},"description":"Credited authors in display order. Authors deleted since they were assigned are omitted."},"featured":{"type":"boolean","description":"Pinned to the top of the blog index on hosted sites.","example":false},"noindex":{"type":"boolean","description":"Asks search engines not to index the post and leaves it out of the sitemap.","example":false},"hidden":{"type":"boolean","description":"Reachable by direct link, but excluded from hosted site listings, feeds, search engine indexing, sitemaps and generated AI indexes. Not private.","example":false},"displayDate":{"type":["string","null"],"description":"Date shown on the post as YYYY-MM-DD. Null means the publish date is used.","example":"2026-10-01"}},"required":["coverImage","tags","excerpt","authors","featured","noindex","hidden","displayDate"],"description":"Cover image, tags, excerpt, authors and other site metadata. Set for blog posts and changelogs, null for every other content type."},"status":{"type":"string","enum":["draft","published"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","slug","content","htmlUrl","markdown","rawHtml","recommendations","contentType","metadata","status","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1},"currentPage":{"type":"integer","minimum":1},"nextPage":{"type":["integer","null"],"minimum":1},"previousPage":{"type":["integer","null"],"minimum":1},"totalPages":{"type":"integer","minimum":1},"totalItems":{"type":"integer","minimum":0}},"required":["limit","currentPage","nextPage","previousPage","totalPages","totalItems"]}},"required":["organization","posts","pagination"]}}}},"400":{"description":"Invalid path params or query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Content"],"operationId":"createPost","summary":"Create a post","description":"Creates a post directly without generation. Omit markdown to create an empty draft you fill in later through the dashboard or PATCH /v1/posts/{postId}. Slugs are only accepted for blog posts and changelogs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"contentType":{"type":"string","enum":["blog_post","changelog","linkedin_post","twitter_post"]},"slug":{"type":["string","null"],"minLength":1,"maxLength":160},"markdown":{"type":"string","maxLength":100000},"status":{"type":"string","enum":["draft","published"],"default":"draft"}},"required":["title","contentType"],"description":"Slugs are normalized to lowercase letters, numbers, and hyphens and only accepted for blog posts and changelogs. Omit markdown to create an empty post you fill in later.","example":{"title":"Ship notes for week 11","contentType":"blog_post","slug":"ship-notes-week-11","status":"draft"}}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"post":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":["string","null"]},"content":{"type":"string","description":"Rendered HTML for text posts. For image posts, this is the public CDN URL of the rendered image."},"htmlUrl":{"type":["string","null"],"description":"Public CDN URL of the generated HTML artifact for image posts. Null for non-image posts."},"markdown":{"type":["string","null"],"description":"Markdown source for text posts. Null for image posts."},"rawHtml":{"type":["string","null"],"description":"Legacy inline generated HTML for image posts. New generated image HTML is stored as htmlUrl. Null for non-image posts."},"recommendations":{"type":["string","null"]},"contentType":{"type":"string","enum":["changelog","linkedin_post","twitter_post","blog_post","investor_update","image"]},"sourceMetadata":{},"metadata":{"type":["object","null"],"properties":{"coverImage":{"type":["object","null"],"properties":{"url":{"type":"string","description":"Absolute https URL, or a path to an image uploaded in Notra (starting with /api/uploads/).","example":"https://cdn.example.com/covers/ship-notes.png"},"alt":{"type":"string","description":"Alt text. Empty string when none is set.","example":"Screenshot of the new editor"}},"required":["url","alt"],"description":"Cover image shown on post cards and social previews."},"tags":{"type":"array","items":{"type":"string"},"example":["editor","performance"]},"excerpt":{"type":["string","null"],"description":"Summary shown on post cards and in meta descriptions. Null means it is derived from the first paragraph.","example":"The editor now opens twice as fast on long posts."},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"auth_8f2kq1"},"slug":{"type":"string","description":"Stable author handle; hosted sites list the author's posts at /author/{slug}.","example":"jane-doe"},"name":{"type":"string","example":"Jane Doe"},"title":{"type":["string","null"],"example":"Head of Product"},"avatarUrl":{"type":["string","null"],"example":"https://cdn.example.com/avatars/jane.png"},"url":{"type":["string","null"],"description":"Author's website.","example":"https://janedoe.dev"},"x":{"type":["string","null"],"example":"https://x.com/janedoe"},"linkedin":{"type":["string","null"]},"github":{"type":["string","null"]},"youtube":{"type":["string","null"]},"bluesky":{"type":["string","null"]},"mastodon":{"type":["string","null"]},"threads":{"type":["string","null"]},"instagram":{"type":["string","null"]}},"required":["id","slug","name","title","avatarUrl","url","x","linkedin","github","youtube","bluesky","mastodon","threads","instagram"]},"description":"Credited authors in display order. Authors deleted since they were assigned are omitted."},"featured":{"type":"boolean","description":"Pinned to the top of the blog index on hosted sites.","example":false},"noindex":{"type":"boolean","description":"Asks search engines not to index the post and leaves it out of the sitemap.","example":false},"hidden":{"type":"boolean","description":"Reachable by direct link, but excluded from hosted site listings, feeds, search engine indexing, sitemaps and generated AI indexes. Not private.","example":false},"displayDate":{"type":["string","null"],"description":"Date shown on the post as YYYY-MM-DD. Null means the publish date is used.","example":"2026-10-01"}},"required":["coverImage","tags","excerpt","authors","featured","noindex","hidden","displayDate"],"description":"Cover image, tags, excerpt, authors and other site metadata. Set for blog posts and changelogs, null for every other content type."},"status":{"type":"string","enum":["draft","published"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","slug","content","htmlUrl","markdown","rawHtml","recommendations","contentType","metadata","status","createdAt","updatedAt"]}},"required":["organization","post"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Post slug already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 60 requests per 1 minute per API key.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/posts/authors":{"get":{"tags":["Content"],"operationId":"listPostAuthors","summary":"List post authors","description":"Returns the organization's authors, sorted by name. Authors are created in the dashboard; pass their IDs in metadata.authorIds when updating a blog post or changelog.","responses":{"200":{"description":"Authors fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pass this ID in metadata.authorIds when updating a post.","example":"auth_8f2kq1"},"slug":{"type":"string","example":"jane-doe"},"name":{"type":"string","example":"Jane Doe"},"title":{"type":["string","null"],"example":"Head of Product"},"bio":{"type":["string","null"]},"avatarUrl":{"type":["string","null"]},"url":{"type":["string","null"],"description":"Author's website.","example":"https://janedoe.dev"},"x":{"type":["string","null"],"example":"https://x.com/janedoe"},"linkedin":{"type":["string","null"]},"github":{"type":["string","null"]},"youtube":{"type":["string","null"]},"bluesky":{"type":["string","null"]},"mastodon":{"type":["string","null"]},"threads":{"type":["string","null"]},"instagram":{"type":["string","null"]}},"required":["id","slug","name","title","bio","avatarUrl","url","x","linkedin","github","youtube","bluesky","mastodon","threads","instagram"]}}},"required":["organization","authors"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/posts/{postId}":{"get":{"tags":["Content"],"operationId":"getPost","summary":"Get a single post","description":"Returns the post. When no post with this ID exists in your organization, the response is still 200 with post set to null. Blog posts and changelogs include a metadata object with cover image, tags, excerpt, authors, featured, noindex, hidden and displayDate; it is null for other content types.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"post_123"},"required":true,"in":"path","name":"postId"}],"responses":{"200":{"description":"Post fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"post":{"type":["object","null"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":["string","null"]},"content":{"type":"string","description":"Rendered HTML for text posts. For image posts, this is the public CDN URL of the rendered image."},"htmlUrl":{"type":["string","null"],"description":"Public CDN URL of the generated HTML artifact for image posts. Null for non-image posts."},"markdown":{"type":["string","null"],"description":"Markdown source for text posts. Null for image posts."},"rawHtml":{"type":["string","null"],"description":"Legacy inline generated HTML for image posts. New generated image HTML is stored as htmlUrl. Null for non-image posts."},"recommendations":{"type":["string","null"]},"contentType":{"type":"string","enum":["changelog","linkedin_post","twitter_post","blog_post","investor_update","image"]},"sourceMetadata":{},"metadata":{"type":["object","null"],"properties":{"coverImage":{"type":["object","null"],"properties":{"url":{"type":"string","description":"Absolute https URL, or a path to an image uploaded in Notra (starting with /api/uploads/).","example":"https://cdn.example.com/covers/ship-notes.png"},"alt":{"type":"string","description":"Alt text. Empty string when none is set.","example":"Screenshot of the new editor"}},"required":["url","alt"],"description":"Cover image shown on post cards and social previews."},"tags":{"type":"array","items":{"type":"string"},"example":["editor","performance"]},"excerpt":{"type":["string","null"],"description":"Summary shown on post cards and in meta descriptions. Null means it is derived from the first paragraph.","example":"The editor now opens twice as fast on long posts."},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"auth_8f2kq1"},"slug":{"type":"string","description":"Stable author handle; hosted sites list the author's posts at /author/{slug}.","example":"jane-doe"},"name":{"type":"string","example":"Jane Doe"},"title":{"type":["string","null"],"example":"Head of Product"},"avatarUrl":{"type":["string","null"],"example":"https://cdn.example.com/avatars/jane.png"},"url":{"type":["string","null"],"description":"Author's website.","example":"https://janedoe.dev"},"x":{"type":["string","null"],"example":"https://x.com/janedoe"},"linkedin":{"type":["string","null"]},"github":{"type":["string","null"]},"youtube":{"type":["string","null"]},"bluesky":{"type":["string","null"]},"mastodon":{"type":["string","null"]},"threads":{"type":["string","null"]},"instagram":{"type":["string","null"]}},"required":["id","slug","name","title","avatarUrl","url","x","linkedin","github","youtube","bluesky","mastodon","threads","instagram"]},"description":"Credited authors in display order. Authors deleted since they were assigned are omitted."},"featured":{"type":"boolean","description":"Pinned to the top of the blog index on hosted sites.","example":false},"noindex":{"type":"boolean","description":"Asks search engines not to index the post and leaves it out of the sitemap.","example":false},"hidden":{"type":"boolean","description":"Reachable by direct link, but excluded from hosted site listings, feeds, search engine indexing, sitemaps and generated AI indexes. Not private.","example":false},"displayDate":{"type":["string","null"],"description":"Date shown on the post as YYYY-MM-DD. Null means the publish date is used.","example":"2026-10-01"}},"required":["coverImage","tags","excerpt","authors","featured","noindex","hidden","displayDate"],"description":"Cover image, tags, excerpt, authors and other site metadata. Set for blog posts and changelogs, null for every other content type."},"status":{"type":"string","enum":["draft","published"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","slug","content","htmlUrl","markdown","rawHtml","recommendations","contentType","metadata","status","createdAt","updatedAt"]}},"required":["organization","post"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Content"],"operationId":"deletePost","summary":"Delete a single post","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"post_123"},"required":true,"in":"path","name":"postId"}],"responses":{"200":{"description":"Post deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","organization"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Content"],"operationId":"updatePost","summary":"Update a single post","description":"Updates any combination of title, slug, markdown, status, and metadata. Sending markdown re-renders the stored HTML, and when title is omitted it is taken from the first heading in the markdown, keeping the existing title when the markdown has no heading. Slugs and metadata are only accepted for blog posts and changelogs. Inside metadata, send only the fields you want to change; tags and authorIds replace the stored list, and authorIds must come from GET /v1/posts/authors. Title, slug, markdown, or metadata updates also sync a post linked to GitHub: an open pull request gets a new commit, and a repository set to publish directly gets a direct commit when its live branch allows one (unprotected, file unchanged on GitHub). Otherwise, including closed or merged pull requests, GitHub is left as is and no new pull request is opened; the post is still saved. GitHub sync errors occur after saving the post: 429 includes Retry-After, 502 indicates a sync error, and 504 indicates an unknown sync outcome. Check the PR before retrying an unconfirmed sync.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"post_123"},"required":true,"in":"path","name":"postId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120,"example":"Ship notes for week 11"},"slug":{"type":["string","null"],"minLength":1,"maxLength":160,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","example":"ship-notes-week-11"},"markdown":{"type":"string","minLength":1,"maxLength":100000,"example":"# Ship notes\n\nWe shipped a faster editor."},"status":{"type":"string","enum":["draft","published"],"example":"published"},"metadata":{"type":"object","properties":{"coverImage":{"type":["object","null"],"properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"alt":{"type":"string","maxLength":300,"default":""}},"required":["url"],"description":"Cover image as { url, alt }. url must be an https URL (or a Notra upload path returned by the dashboard). Send null to remove the cover.","example":{"url":"https://cdn.example.com/covers/ship-notes.png","alt":"Screenshot of the new editor"}},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":12,"description":"Replaces all tags. Up to 12 tags; duplicates are dropped case-insensitively, keeping the first spelling. Send [] to clear.","example":["editor","performance"]},"excerpt":{"type":["string","null"],"maxLength":300,"description":"Custom summary for post cards and meta descriptions. Send null or an empty string to derive it from the first paragraph again.","example":"The editor now opens twice as fast on long posts."},"authorIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":5,"description":"Replaces the credited authors, in display order. Up to 5 IDs from GET /v1/posts/authors. Send [] to clear.","example":["auth_8f2kq1"]},"featured":{"type":"boolean","description":"Pin the post to the top of the blog index.","example":true},"noindex":{"type":"boolean","description":"Ask search engines not to index the post and leave it out of the sitemap.","example":false},"hidden":{"type":"boolean","description":"Hide the post from hosted site listings, feeds, search engine indexing, sitemaps and generated AI indexes while keeping its direct URL accessible. Not private.","example":true},"displayDate":{"type":["string","null"],"format":"date","description":"Date shown on the post as YYYY-MM-DD. Send null to fall back to the publish date.","example":"2026-10-01"}},"description":"Site metadata for blog posts and changelogs. Send only the fields you want to change. Rejected with 400 for other content types."}}}}}},"responses":{"200":{"description":"Post updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"post":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":["string","null"]},"content":{"type":"string","description":"Rendered HTML for text posts. For image posts, this is the public CDN URL of the rendered image."},"htmlUrl":{"type":["string","null"],"description":"Public CDN URL of the generated HTML artifact for image posts. Null for non-image posts."},"markdown":{"type":["string","null"],"description":"Markdown source for text posts. Null for image posts."},"rawHtml":{"type":["string","null"],"description":"Legacy inline generated HTML for image posts. New generated image HTML is stored as htmlUrl. Null for non-image posts."},"recommendations":{"type":["string","null"]},"contentType":{"type":"string","enum":["changelog","linkedin_post","twitter_post","blog_post","investor_update","image"]},"sourceMetadata":{},"metadata":{"type":["object","null"],"properties":{"coverImage":{"type":["object","null"],"properties":{"url":{"type":"string","description":"Absolute https URL, or a path to an image uploaded in Notra (starting with /api/uploads/).","example":"https://cdn.example.com/covers/ship-notes.png"},"alt":{"type":"string","description":"Alt text. Empty string when none is set.","example":"Screenshot of the new editor"}},"required":["url","alt"],"description":"Cover image shown on post cards and social previews."},"tags":{"type":"array","items":{"type":"string"},"example":["editor","performance"]},"excerpt":{"type":["string","null"],"description":"Summary shown on post cards and in meta descriptions. Null means it is derived from the first paragraph.","example":"The editor now opens twice as fast on long posts."},"authors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"auth_8f2kq1"},"slug":{"type":"string","description":"Stable author handle; hosted sites list the author's posts at /author/{slug}.","example":"jane-doe"},"name":{"type":"string","example":"Jane Doe"},"title":{"type":["string","null"],"example":"Head of Product"},"avatarUrl":{"type":["string","null"],"example":"https://cdn.example.com/avatars/jane.png"},"url":{"type":["string","null"],"description":"Author's website.","example":"https://janedoe.dev"},"x":{"type":["string","null"],"example":"https://x.com/janedoe"},"linkedin":{"type":["string","null"]},"github":{"type":["string","null"]},"youtube":{"type":["string","null"]},"bluesky":{"type":["string","null"]},"mastodon":{"type":["string","null"]},"threads":{"type":["string","null"]},"instagram":{"type":["string","null"]}},"required":["id","slug","name","title","avatarUrl","url","x","linkedin","github","youtube","bluesky","mastodon","threads","instagram"]},"description":"Credited authors in display order. Authors deleted since they were assigned are omitted."},"featured":{"type":"boolean","description":"Pinned to the top of the blog index on hosted sites.","example":false},"noindex":{"type":"boolean","description":"Asks search engines not to index the post and leaves it out of the sitemap.","example":false},"hidden":{"type":"boolean","description":"Reachable by direct link, but excluded from hosted site listings, feeds, search engine indexing, sitemaps and generated AI indexes. Not private.","example":false},"displayDate":{"type":["string","null"],"description":"Date shown on the post as YYYY-MM-DD. Null means the publish date is used.","example":"2026-10-01"}},"required":["coverImage","tags","excerpt","authors","featured","noindex","hidden","displayDate"],"description":"Cover image, tags, excerpt, authors and other site metadata. Set for blog posts and changelogs, null for every other content type."},"status":{"type":"string","enum":["draft","published"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","slug","content","htmlUrl","markdown","rawHtml","recommendations","contentType","metadata","status","createdAt","updatedAt"]}},"required":["organization","post"]}}}},"400":{"description":"Invalid path params or request body, slug or metadata sent for an unsupported content type, or an unknown author ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Post slug already exists or concurrent modification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Post update or GitHub publish rate limit exceeded. The error states whether the post was already saved; Retry-After specifies when to retry.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"502":{"description":"Post saved, but linked GitHub pull request sync failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Post saved; GitHub sync timed out with an unknown outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/posts/generate":{"post":{"tags":["Content"],"operationId":"createPostGeneration","summary":"Queue async post generation","description":"Queues a generation job for one content type and returns 202 with the job. Select sources with integrations.github, integrations.linear, or github.repositories; when no selector is given at all, every connected GitHub integration is used. Requests with every dataPoints flag false, or with no usable source, are rejected with 400 and code NO_ACTIVITY_TYPES_SELECTED or NO_AVAILABLE_SOURCES before a job is created. Poll GET /v1/posts/generate/{jobId} until job.status is completed, failed, or skipped. Subscribe to post.generation.completed, post.generation.failed, or post.generation.skipped using /v1/webhooks for completion notifications.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"],"description":"Type of content to generate.","example":"blog_post"},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"],"default":"last_7_days","description":"How far back to collect source activity (commits, pull requests, releases, Linear issues).","example":"last_7_days"},"brandVoiceId":{"type":"string","minLength":1,"description":"Deprecated. Use brandIdentityId instead.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"brandIdentityId":{"type":["string","null"],"minLength":1,"description":"Brand identity to write in. Defaults to the organization's default brand identity.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"example":["repo_1","repo_2"],"description":"Deprecated. Use integrations.github with GitHub integration IDs instead."},"linearIntegrationIds":{"type":"array","items":{"type":"string","minLength":1},"example":["linear_integration_1"],"description":"Deprecated. Use integrations.linear with Linear integration IDs instead."},"integrations":{"type":"object","properties":{"github":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"GitHub integration IDs to use as sources, as returned by GET /v1/integrations.","example":["integration_1","integration_2"]},"linear":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"description":"Linear integration IDs to use as sources, as returned by GET /v1/integrations.","example":["linear_integration_1"]}},"description":"Source integrations to draw activity from. Omit this and github.repositories to use every connected GitHub integration."},"github":{"type":"object","properties":{"repositories":{"type":"array","items":{"type":"object","properties":{"owner":{"type":"string","minLength":1},"repo":{"type":"string","minLength":1}},"required":["owner","repo"]},"minItems":1}},"required":["repositories"],"description":"Select connected repositories by owner and name instead of integration ID. Cannot be combined with integrations.github.","example":{"repositories":[{"owner":"usenotra","repo":"notra"}]}},"dataPoints":{"type":"object","properties":{"includePullRequests":{"type":"boolean","default":true},"includeCommits":{"type":"boolean","default":true},"includeReleases":{"type":"boolean","default":true},"includeLinearData":{"type":"boolean","default":false}},"default":{"includePullRequests":true,"includeCommits":true,"includeReleases":true,"includeLinearData":false},"description":"Which kinds of activity to collect from the selected sources. At least one must be true."},"selectedItems":{"type":"object","properties":{"commitShas":{"type":"array","items":{"type":"string"}},"pullRequestNumbers":{"type":"array","items":{"type":"object","properties":{"repositoryId":{"type":"string"},"number":{"type":"number"}},"required":["repositoryId","number"]}},"releaseTagNames":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","properties":{"repositoryId":{"type":"string"},"tagName":{"type":"string"}},"required":["repositoryId","tagName"]}]}},"linearIssueIds":{"type":"array","items":{"type":"object","properties":{"integrationId":{"type":"string"},"issueId":{"type":"string"}},"required":["integrationId","issueId"]}}},"description":"Restrict generation to specific commits, pull requests, releases, or Linear issues instead of everything in the lookback window."},"timezone":{"type":"string","minLength":1,"maxLength":100,"description":"IANA timezone used for relative lookback windows such as current_day and yesterday.","example":"America/New_York"}},"required":["contentType"]}}}},"responses":{"202":{"description":"Post generation queued successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed","skipped"],"description":"Job state. Terminal states are completed, failed, and skipped."},"contentType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"]},"repositoryIds":{"type":"array","items":{"type":"string"}},"brandVoiceId":{"type":["string","null"]},"workflowRunId":{"type":["string","null"]},"postId":{"type":["string","null"],"description":"ID of the generated post. Set once the job reaches completed."},"error":{"type":["string","null"],"description":"Failure reason when status is failed."},"errorCode":{"type":["string","null"],"description":"Stable machine-readable failure code when status is failed, such as NO_ACTIVITY_TYPES_SELECTED or NO_AVAILABLE_SOURCES. Absent or null for other failures and for older jobs.","example":"NO_AVAILABLE_SOURCES"},"source":{"type":"string","enum":["api","dashboard"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","organizationId","status","contentType","lookbackWindow","repositoryIds","brandVoiceId","workflowRunId","postId","error","source","createdAt","updatedAt","completedAt"]}},"required":["organization","job"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 1 minute per API key.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Content generation is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"jobId":{"type":"string"}},"required":["error"]}}}}}}},"/v1/posts/generate/{jobId}":{"get":{"tags":["Content"],"operationId":"getPostGeneration","summary":"Get async post generation status","description":"Returns the job and its event log. job.status moves from queued to running and ends as completed, failed, or skipped. job.postId is set once the post has been created; fetch it with GET /v1/posts/{postId}.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"Job ID returned by POST /v1/posts/generate.","example":"job_5f0c3b2a9d4e4c1f8a7b6c5d4e3f2a1b"},"required":true,"description":"Job ID returned by POST /v1/posts/generate.","in":"path","name":"jobId"}],"responses":{"200":{"description":"Post generation status fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed","skipped"],"description":"Job state. Terminal states are completed, failed, and skipped."},"contentType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"]},"repositoryIds":{"type":"array","items":{"type":"string"}},"brandVoiceId":{"type":["string","null"]},"workflowRunId":{"type":["string","null"]},"postId":{"type":["string","null"],"description":"ID of the generated post. Set once the job reaches completed."},"error":{"type":["string","null"],"description":"Failure reason when status is failed."},"errorCode":{"type":["string","null"],"description":"Stable machine-readable failure code when status is failed, such as NO_ACTIVITY_TYPES_SELECTED or NO_AVAILABLE_SOURCES. Absent or null for other failures and for older jobs.","example":"NO_AVAILABLE_SOURCES"},"source":{"type":"string","enum":["api","dashboard"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","organizationId","status","contentType","lookbackWindow","repositoryIds","brandVoiceId","workflowRunId","postId","error","source","createdAt","updatedAt","completedAt"]},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"jobId":{"type":"string"},"type":{"type":"string","enum":["queued","workflow_triggered","running","fetching_repositories","generating_content","post_created","completed","failed","skipped"]},"message":{"type":"string"},"createdAt":{"type":"string"},"metadata":{"type":["object","null"],"additionalProperties":{}}},"required":["id","jobId","type","message","createdAt","metadata"]}}},"required":["job","events"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Generation job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Content generation is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"operationId":"listWebhookEndpoints","summary":"List outbound webhook subscriptions","responses":{"200":{"description":"Endpoints, without signing secrets","content":{"application/json":{"schema":{"type":"object","properties":{"endpoints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["post.generation.completed","post.generation.failed","post.generation.skipped","brand_identity.generation.completed","brand_identity.generation.failed","post.published","post.created","post.updated","post.deleted","post.unpublished","geo.scan.completed","geo.scan.failed","geo.alert.triggered"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","organizationId","url","events","enabled","createdAt"]}}},"required":["endpoints"]}}}},"400":{"description":"Invalid webhook request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Subscription verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhooks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Webhooks"],"operationId":"createWebhookEndpoint","summary":"Subscribe an HTTPS endpoint to Notra events","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["post.generation.completed","post.generation.failed","post.generation.skipped","brand_identity.generation.completed","brand_identity.generation.failed","post.published","post.created","post.updated","post.deleted","post.unpublished","geo.scan.completed","geo.scan.failed","geo.alert.triggered"]},"minItems":1,"maxItems":13}},"required":["url","events"]}}}},"responses":{"201":{"description":"Endpoint and one-time signing secret","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["post.generation.completed","post.generation.failed","post.generation.skipped","brand_identity.generation.completed","brand_identity.generation.failed","post.published","post.created","post.updated","post.deleted","post.unpublished","geo.scan.completed","geo.scan.failed","geo.alert.triggered"]}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","organizationId","url","events","enabled","createdAt"]},"secret":{"type":"string"}},"required":["endpoint","secret"]}}}},"400":{"description":"Invalid webhook request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Subscription verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhooks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks/{endpointId}":{"delete":{"tags":["Webhooks"],"operationId":"deleteWebhookEndpoint","summary":"Remove a webhook subscription and cancel unsent deliveries","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"endpointId","in":"path"}],"responses":{"200":{"description":"Deleted endpoint ID","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"400":{"description":"Invalid webhook request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Subscription verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhooks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks/deliveries":{"get":{"tags":["Webhooks"],"operationId":"listWebhookDeliveries","summary":"List webhook deliveries","parameters":[{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"string","enum":["all","pending","sending","retrying","succeeded","failed","cancelled"],"default":"all"},"required":false,"name":"status","in":"query"}],"responses":{"200":{"description":"Delivery history","content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"endpointId":{"type":"string"},"url":{"type":"string"},"eventType":{"type":"string","enum":["post.generation.completed","post.generation.failed","post.generation.skipped","brand_identity.generation.completed","brand_identity.generation.failed","post.published","post.created","post.updated","post.deleted","post.unpublished","geo.scan.completed","geo.scan.failed","geo.alert.triggered"]},"status":{"type":"string","enum":["pending","sending","retrying","succeeded","failed","cancelled"]},"attemptCount":{"type":"number"},"nextAttemptAt":{"type":"string"},"createdAt":{"type":"string"},"statusCode":{"type":["number","null"]},"error":{"type":["string","null"]}},"required":["id","eventId","endpointId","url","eventType","status","attemptCount","nextAttemptAt","createdAt","statusCode","error"]}},"hasMore":{"type":"boolean"}},"required":["deliveries","hasMore"]}}}},"400":{"description":"Invalid webhook request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Subscription verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhooks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks/deliveries/{deliveryId}":{"get":{"tags":["Webhooks"],"operationId":"getWebhookDelivery","summary":"Get payload and attempt history for a delivery","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"deliveryId","in":"path"}],"responses":{"200":{"description":"Delivery detail","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"endpointId":{"type":"string"},"url":{"type":"string"},"eventType":{"type":"string","enum":["post.generation.completed","post.generation.failed","post.generation.skipped","brand_identity.generation.completed","brand_identity.generation.failed","post.published","post.created","post.updated","post.deleted","post.unpublished","geo.scan.completed","geo.scan.failed","geo.alert.triggered"]},"status":{"type":"string","enum":["pending","sending","retrying","succeeded","failed","cancelled"]},"attemptCount":{"type":"number"},"nextAttemptAt":{"type":"string"},"createdAt":{"type":"string"},"statusCode":{"type":["number","null"]},"error":{"type":["string","null"]},"payload":{"type":"string"}},"required":["id","eventId","endpointId","url","eventType","status","attemptCount","nextAttemptAt","createdAt","statusCode","error","payload"]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"deliveryId":{"type":"string"},"attemptNumber":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"type":["string","null"]},"statusCode":{"type":["number","null"]},"error":{"type":["string","null"]},"durationMs":{"type":["number","null"]}},"required":["id","deliveryId","attemptNumber","startedAt","finishedAt","statusCode","error","durationMs"]}}},"required":["delivery","attempts"]}}}},"400":{"description":"Invalid webhook request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Subscription verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhooks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/webhooks/deliveries/{deliveryId}/retry":{"post":{"tags":["Webhooks"],"operationId":"retryWebhookDelivery","summary":"Retry a failed delivery, retaining its history","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"deliveryId","in":"path"}],"responses":{"200":{"description":"Queued delivery ID","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}}},"400":{"description":"Invalid webhook request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Webhook not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Subscription verification failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Webhooks unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/posts/{postId}/schedule":{"get":{"tags":["Content"],"operationId":"getPostSchedule","summary":"Get a post's publishing schedule","description":"Returns the post's current schedule with the state of every destination, or null when nothing is scheduled.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"post_123"},"required":true,"in":"path","name":"postId"}],"responses":{"200":{"description":"Schedule fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostScheduleResponse"}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization or post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Content"],"operationId":"schedulePost","summary":"Schedule a post for publishing","description":"Publishes the post automatically at scheduledAt: it is marked as published in Notra and, optionally, opened and merged as a GitHub pull request or posted to a connected X or LinkedIn account. Replaces any schedule that has not started. The post is published as saved at that time, so later edits are included. Publishing runs within about a minute of scheduledAt; transient errors are retried automatically.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"post_123"},"required":true,"in":"path","name":"postId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulePostRequest"}}}},"responses":{"200":{"description":"Post scheduled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostScheduleResponse"}}}},"400":{"description":"Invalid request body or destination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Post is publishing or the schedule changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 60 requests per 1 minute per API key.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Content"],"operationId":"cancelPostSchedule","summary":"Cancel a post's publishing schedule","description":"Cancels every destination that has not started and clears failed ones. A destination that is already publishing cannot be interrupted: it finishes if it succeeds and ends canceled instead of being retried. inProgress reports it.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"post_123"},"required":true,"in":"path","name":"postId"}],"responses":{"200":{"description":"Schedule canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelPostScheduleResponse"}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization or post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 60 requests per 1 minute per API key.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/posts/{postId}/agent-reach":{"get":{"tags":["Content"],"operationId":"getPostAgentReach","summary":"Get a post's agent reach","description":"Returns AI crawler, citation and referral visits to the post's live page on its Notra Site, including its Markdown copy. Defaults to the last 30 days. agentReach is null when the post isn't live on a Site.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"post_123"},"required":true,"in":"path","name":"postId"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Agent reach fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostAgentReachResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization or post not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/brand-identities":{"get":{"tags":["Content"],"operationId":"listBrandIdentities","summary":"List available brand identities","description":"Returns every brand identity in the organization, default identity first.","responses":{"200":{"description":"Brand identities fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"brandIdentities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"isDefault":{"type":"boolean"},"websiteUrl":{"type":"string"},"companyName":{"type":["string","null"]},"companyDescription":{"type":["string","null"]},"toneProfile":{"type":["string","null"]},"customTone":{"type":["string","null"]},"customInstructions":{"type":["string","null"]},"audience":{"type":["string","null"]},"language":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","isDefault","websiteUrl","companyName","companyDescription","toneProfile","customTone","customInstructions","audience","language","createdAt","updatedAt"]}}},"required":["organization","brandIdentities"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/brand-identities/generate":{"post":{"tags":["Content"],"operationId":"createBrandIdentity","summary":"Queue async brand identity generation","description":"Creates the brand identity immediately, then queues a website analysis that fills in company details, tone, and audience. The first brand identity in an organization becomes the default. Poll GET /v1/brand-identities/generate/{jobId} until job.status is completed or failed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Display name. Must be unique within the organization. Defaults to \"Untitled Brand Voice\".","example":"Notra"},"websiteUrl":{"type":"string","minLength":1,"description":"Public website to analyze for company details, tone, and audience. The scheme is optional; https is assumed.","example":"https://usenotra.com"}},"required":["websiteUrl"]}}}},"responses":{"202":{"description":"Brand identity generation queued successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"brandIdentityId":{"type":"string","description":"ID of the brand identity being analyzed. The identity is created immediately and its details are filled in as the job completes."},"status":{"type":"string","enum":["queued","running","completed","failed"],"description":"Job state. Stop polling once it is completed or failed."},"step":{"type":["string","null"],"enum":["scraping","extracting","saving",null],"description":"Current analysis step while the job is running."},"currentStep":{"type":"integer","minimum":0},"totalSteps":{"type":"integer","minimum":1},"workflowRunId":{"type":["string","null"]},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","organizationId","brandIdentityId","status","step","currentStep","totalSteps","workflowRunId","error","createdAt","updatedAt","completedAt"]}},"required":["organization","job"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Brand identity name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 5 requests per 1 minute per API key.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Authentication service or brand analysis unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/brand-identities/generate/{jobId}":{"get":{"tags":["Content"],"operationId":"getBrandIdentityGeneration","summary":"Get async brand identity generation status","description":"Returns the analysis job. job.status moves from queued to running and ends as completed or failed; job.step shows the current stage while running. Fetch the finished identity with GET /v1/brand-identities/{brandIdentityId}.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"Job ID returned by POST /v1/brand-identities/generate.","example":"brand_job_5f0c3b2a9d4e4c1f8a7b6c5d4e3f2a1b"},"required":true,"description":"Job ID returned by POST /v1/brand-identities/generate.","in":"path","name":"jobId"}],"responses":{"200":{"description":"Brand identity generation status fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"job":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"brandIdentityId":{"type":"string","description":"ID of the brand identity being analyzed. The identity is created immediately and its details are filled in as the job completes."},"status":{"type":"string","enum":["queued","running","completed","failed"],"description":"Job state. Stop polling once it is completed or failed."},"step":{"type":["string","null"],"enum":["scraping","extracting","saving",null],"description":"Current analysis step while the job is running."},"currentStep":{"type":"integer","minimum":0},"totalSteps":{"type":"integer","minimum":1},"workflowRunId":{"type":["string","null"]},"error":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"completedAt":{"type":["string","null"]}},"required":["id","organizationId","brandIdentityId","status","step","currentStep","totalSteps","workflowRunId","error","createdAt","updatedAt","completedAt"]}},"required":["organization","job"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand identity analysis job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Brand analysis is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/brand-identities/{brandIdentityId}":{"get":{"tags":["Content"],"operationId":"getBrandIdentity","summary":"Get a single brand identity","description":"Returns the brand identity. When no brand identity with this ID exists in your organization, the response is still 200 with brandIdentity set to null.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"brandIdentityId"}],"responses":{"200":{"description":"Brand identity fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"brandIdentity":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"isDefault":{"type":"boolean"},"websiteUrl":{"type":"string"},"companyName":{"type":["string","null"]},"companyDescription":{"type":["string","null"]},"toneProfile":{"type":["string","null"]},"customTone":{"type":["string","null"]},"customInstructions":{"type":["string","null"]},"audience":{"type":["string","null"]},"language":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","isDefault","websiteUrl","companyName","companyDescription","toneProfile","customTone","customInstructions","audience","language","createdAt","updatedAt"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["brandIdentity","organization"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Content"],"operationId":"updateBrandIdentity","summary":"Update a single brand identity","description":"Updates brand identity fields. Pass isDefault: true to make the target brand identity the organization's default.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"brandIdentityId"}],"requestBody":{"required":true,"content":{"application/json":{"examples":{"setDefault":{"summary":"Set as default","value":{"isDefault":true}},"updateAndSetDefault":{"summary":"Rename and set as default","value":{"name":"Notra Marketing","isDefault":true}},"switchToPresetTone":{"summary":"Switch custom tone to preset","value":{"toneProfile":"Professional"}},"setCustomTone":{"summary":"Set custom tone","value":{"customTone":"Warm, sharp, and opinionated"}}},"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"example":"Notra"},"websiteUrl":{"type":"string","minLength":1,"example":"https://usenotra.com"},"companyName":{"type":["string","null"],"minLength":1,"maxLength":200,"example":"Notra"},"companyDescription":{"type":["string","null"],"minLength":10,"maxLength":4000,"example":"AI-native content workflows for software teams."},"toneProfile":{"type":["string","null"],"enum":["Conversational","Professional","Casual","Formal",null],"example":"Professional","description":"Set a preset tone profile. When provided without customTone, any saved custom tone is cleared."},"customTone":{"type":["string","null"],"maxLength":1000,"example":"Clear, direct, and technically confident","description":"Provide a custom tone override. Send an empty string or null to clear it."},"customInstructions":{"type":["string","null"],"maxLength":4000,"example":"Avoid hype. Prioritize concrete examples."},"audience":{"type":["string","null"],"minLength":10,"maxLength":1000,"example":"Engineering leaders and developer tooling teams."},"language":{"type":["string","null"],"enum":["English","Spanish","French","German","Portuguese","Dutch","Italian","Japanese","Korean","Chinese","Arabic","Hindi","Russian","Turkish","Polish","Swedish","Danish","Norwegian","Finnish","Czech","Romanian","Hungarian","Greek","Thai","Vietnamese","Indonesian","Ukrainian","Hebrew",null],"example":"English"},"isDefault":{"type":"boolean","enum":[true],"example":true,"description":"Set this brand identity as the organization's default. Only true is accepted."}}}}}},"responses":{"200":{"description":"Brand identity updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"brandIdentity":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"isDefault":{"type":"boolean"},"websiteUrl":{"type":"string"},"companyName":{"type":["string","null"]},"companyDescription":{"type":["string","null"]},"toneProfile":{"type":["string","null"]},"customTone":{"type":["string","null"]},"customInstructions":{"type":["string","null"]},"audience":{"type":["string","null"]},"language":{"type":["string","null"]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","isDefault","websiteUrl","companyName","companyDescription","toneProfile","customTone","customInstructions","audience","language","createdAt","updatedAt"]}},"required":["organization","brandIdentity"]}}}},"400":{"description":"Invalid path params or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand identity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Brand identity name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Content"],"operationId":"deleteBrandIdentity","summary":"Delete a single brand identity","description":"Deletes a non-default brand identity and disables any automation triggers that reference it.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"brandIdentityId"}],"responses":{"200":{"description":"Brand identity deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"disabledSchedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"disabledEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"required":["id","organization","disabledSchedules","disabledEvents"]}}}},"400":{"description":"Cannot delete the default brand identity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand identity not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Brand identity is in use by a project or content brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/brand-identities/{brandIdentityId}/colors":{"get":{"tags":["Content"],"operationId":"listBrandColors","summary":"List brand colors","description":"Returns the brand guideline colors of a brand identity.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"brandIdentityId"}],"responses":{"200":{"description":"Brand colors fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"colors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["primary","secondary","accent","background","foreground","neutral","custom"],"example":"primary"},"name":{"type":["string","null"]},"lightValue":{"type":"string","example":"#13A0DC"},"darkValue":{"type":["string","null"]},"usage":{"type":["string","null"]}},"required":["id","role","name","lightValue","darkValue","usage"]}}},"required":["organization","colors"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand identity not found or its brand guidelines have not been generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Content"],"operationId":"createBrandColor","summary":"Add a brand color","description":"Adds a color to the brand guidelines of a brand identity.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"brandIdentityId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["primary","secondary","accent","background","foreground","neutral","custom"],"default":"custom","example":"primary"},"name":{"type":["string","null"],"maxLength":120},"lightValue":{"type":"string","pattern":"^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i","example":"#13A0DC"},"darkValue":{"type":["string","null"],"pattern":"^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i"},"usage":{"type":["string","null"],"maxLength":240}},"required":["lightValue"]}}}},"responses":{"201":{"description":"Brand color created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"color":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["primary","secondary","accent","background","foreground","neutral","custom"],"example":"primary"},"name":{"type":["string","null"]},"lightValue":{"type":"string","example":"#13A0DC"},"darkValue":{"type":["string","null"]},"usage":{"type":["string","null"]}},"required":["id","role","name","lightValue","darkValue","usage"]}},"required":["organization","color"]}}}},"400":{"description":"Invalid path params or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand identity not found or its brand guidelines have not been generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/brand-identities/{brandIdentityId}/colors/{colorId}":{"patch":{"tags":["Content"],"operationId":"updateBrandColor","summary":"Update a brand color","description":"Updates the given fields of a brand color.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"brandIdentityId"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"8f2c1d4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f"},"required":true,"in":"path","name":"colorId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["primary","secondary","accent","background","foreground","neutral","custom"],"example":"primary"},"name":{"type":["string","null"],"maxLength":120},"lightValue":{"type":"string","pattern":"^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i"},"darkValue":{"type":["string","null"],"pattern":"^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i"},"usage":{"type":["string","null"],"maxLength":240}}}}}},"responses":{"200":{"description":"Brand color updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"color":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string","enum":["primary","secondary","accent","background","foreground","neutral","custom"],"example":"primary"},"name":{"type":["string","null"]},"lightValue":{"type":"string","example":"#13A0DC"},"darkValue":{"type":["string","null"]},"usage":{"type":["string","null"]}},"required":["id","role","name","lightValue","darkValue","usage"]}},"required":["organization","color"]}}}},"400":{"description":"Invalid path params or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand color not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Content"],"operationId":"deleteBrandColor","summary":"Delete a brand color","description":"Removes a color from the brand guidelines.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"brandIdentityId"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"8f2c1d4e-5b6a-4c3d-9e8f-7a6b5c4d3e2f"},"required":true,"in":"path","name":"colorId"}],"responses":{"200":{"description":"Brand color deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"id":{"type":"string"}},"required":["organization","id"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Brand color not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/integrations":{"get":{"tags":["Content"],"operationId":"listIntegrations","summary":"List available integrations","description":"Returns the enabled GitHub and Linear integrations for the organization. The slack array is always empty.","responses":{"200":{"description":"Integrations fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"github":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"owner":{"type":["string","null"]},"repo":{"type":["string","null"]},"defaultBranch":{"type":["string","null"]}},"required":["id","displayName","owner","repo","defaultBranch"]},"description":"Enabled GitHub integrations. One entry per connected repository."},"slack":{"type":"array","items":{},"description":"Always empty. Slack is connected from the dashboard and is not exposed through the API."},"linear":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"linearOrganizationId":{"type":"string"},"linearOrganizationName":{"type":["string","null"]},"linearTeamId":{"type":["string","null"]},"linearTeamName":{"type":["string","null"]}},"required":["id","displayName","linearOrganizationId","linearOrganizationName","linearTeamId","linearTeamName"]},"description":"Enabled Linear integrations."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["github","slack","linear","organization"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/integrations/github":{"post":{"tags":["Content"],"operationId":"createGitHubIntegration","summary":"Create a GitHub integration","description":"Checks that the repository can be read (a personal access token is required for private repositories), connects it, and enables changelog generation for it; blog post and X post outputs start disabled. A webhook secret is generated on creation. Copy the payload URL and secret from the dashboard to receive push and release events.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"owner":{"type":"string","minLength":1,"description":"GitHub user or organization that owns the repository.","example":"usenotra"},"repo":{"type":"string","minLength":1,"description":"Repository name without the owner.","example":"notra"},"branch":{"type":["string","null"],"minLength":1,"description":"Branch to read activity from. Defaults to the repository's default branch.","example":"main"},"token":{"type":["string","null"],"minLength":1,"description":"GitHub personal access token with read access to the repository. Required for private repositories; public repositories work without one.","example":"github_pat_11ABCDEFG..."}},"required":["owner","repo"]}}}},"responses":{"201":{"description":"GitHub integration created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"github":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"owner":{"type":["string","null"]},"repo":{"type":["string","null"]},"defaultBranch":{"type":["string","null"]}},"required":["id","displayName","owner","repo","defaultBranch"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["github","organization"]}}}},"400":{"description":"Invalid request body or GitHub repository access error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Repository already connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 20 requests per 1 minute per API key.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Authentication or integration service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/integrations/github/{integrationId}/activity":{"get":{"tags":["Content"],"operationId":"getGitHubActivity","summary":"List recent GitHub activity","description":"Lists pull requests merged into the default branch, commits on the default branch, or releases published in a connected repository within a time window, so you can decide what to write about before calling create_post or generate_post. Reads GitHub live; pagination follows GitHub's pages, so a page can hold fewer items than the page size while nextPage is still set.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"integrationId"},{"schema":{"type":"string","enum":["pull_requests","commits","releases"],"default":"pull_requests","description":"Activity to list: pull requests merged into the default branch, commits on the default branch, or releases published in the repository.","example":"pull_requests"},"required":false,"description":"Activity to list: pull requests merged into the default branch, commits on the default branch, or releases published in the repository.","name":"type","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Start of the window (ISO 8601). Defaults to 7 days ago.","example":"2026-10-23T00:00:00Z"},"required":false,"description":"Start of the window (ISO 8601). Defaults to 7 days ago.","name":"since","in":"query"},{"schema":{"type":"string","format":"date-time","description":"End of the window (ISO 8601). Defaults to now.","example":"2026-10-30T00:00:00Z"},"required":false,"description":"End of the window (ISO 8601). Defaults to now.","name":"until","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number","example":1},"required":false,"description":"Page number","name":"page","in":"query"}],"responses":{"200":{"description":"Activity fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"integration":{"type":"object","properties":{"id":{"type":"string"},"displayName":{"type":"string"},"owner":{"type":["string","null"]},"repo":{"type":["string","null"]},"defaultBranch":{"type":["string","null"]}},"required":["id","displayName","owner","repo","defaultBranch"]},"type":{"type":"string","enum":["pull_requests","commits","releases"]},"since":{"type":"string"},"until":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","description":"Pull request number, commit SHA or release tag, depending on type.","example":"482"},"title":{"type":"string"},"body":{"type":["string","null"]},"author":{"type":["string","null"]},"url":{"type":"string"},"occurredAt":{"type":"string","description":"Merge, commit or publish time (ISO 8601)."}},"required":["ref","title","body","author","url","occurredAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"nextPage":{"type":["integer","null"]}},"required":["page","nextPage"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["integration","type","since","until","items","pagination","organization"]}}}},"400":{"description":"Invalid request or repository no longer readable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"GitHub integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"GitHub unavailable or rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/integrations/{integrationId}":{"delete":{"tags":["Content"],"operationId":"deleteIntegration","summary":"Delete a single integration","description":"Deletes a GitHub or Linear integration. Schedules and event triggers that target the integration are disabled and listed in the response.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"required":true,"in":"path","name":"integrationId"}],"responses":{"200":{"description":"Integration deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]},"disabledSchedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"disabledEvents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}}},"required":["id","organization","disabledSchedules","disabledEvents"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/schedules":{"get":{"tags":["Schedules"],"operationId":"listSchedules","summary":"List schedules","description":"Returns the organization's cron schedules, newest first. repositoryMap maps each targeted GitHub integration ID to an owner/repo label.","parameters":[{"schema":{"type":"string","description":"Filter by GitHub integration IDs using a comma-separated list. Only schedules targeting at least one of them are returned.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561,7f9a2b3c-1d4e-4f5a-9b6c-8d7e6f5a4b3c"},"required":false,"description":"Filter by GitHub integration IDs using a comma-separated list. Only schedules targeting at least one of them are returned.","name":"repositoryIds","in":"query"}],"responses":{"200":{"description":"Schedules fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"schedules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"sourceType":{"type":"string","enum":["cron"]},"sourceConfig":{"type":"object","properties":{"cron":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","custom"],"description":"How often the schedule runs.","example":"weekly"},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day to run, in UTC (0-23).","example":9},"minute":{"type":"integer","minimum":0,"maximum":59,"description":"Minute of the hour to run (0-59).","example":0},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"Day of the week for weekly schedules, 0 (Sunday) to 6 (Saturday). Required when frequency is weekly.","example":1},"dayOfMonth":{"type":"integer","minimum":1,"maximum":31,"description":"Day of the month for monthly schedules (1-31). Required when frequency is monthly.","example":1},"intervalDays":{"type":"integer","minimum":2,"maximum":90,"description":"Run every N days (2-90). Required when frequency is custom.","example":3},"anchorDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC calendar date (YYYY-MM-DD) a custom interval counts from. Defaults to today.","example":"2026-09-03"}},"required":["frequency","hour","minute"]}},"required":["cron"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string"},"description":"GitHub integration IDs to generate from, as returned in the github array of GET /v1/integrations."},"linearIntegrationIds":{"type":"array","items":{"type":"string"},"description":"Linear integration IDs to generate from, as returned in the linear array of GET /v1/integrations. When omitted, runs read every enabled Linear integration; send [] to read none."}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"],"description":"Where auto-published posts are sent."},"brandVoiceId":{"type":"string","minLength":1,"description":"Brand identity ID to write in. Defaults to the organization's default brand identity.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"instructions":{"type":"string","minLength":1,"maxLength":2000,"description":"Free-text brief for this schedule, passed to the writer on every run on top of the brand's custom instructions. Use it to steer the angle of the content, for example tutorial-style blog posts.","example":"Write a tutorial-style post that walks through one feature shipped in this window, with code samples."},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"],"description":"Where to announce new content after a successful run: Slack posts to the organization's notification channel, email goes to the workspace owners.","example":{"slack":true,"email":false}}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"]}},"required":["id","organizationId","name","sourceType","sourceConfig","targets","outputType","enabled","autoPublish","createdAt","updatedAt","lookbackWindow"]}},"repositoryMap":{"type":"object","additionalProperties":{"type":"string"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["schedules","repositoryMap","organization"]}}}},"400":{"description":"Invalid query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to list schedules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Schedules"],"operationId":"createSchedule","summary":"Create a schedule","description":"Creates a recurring schedule that generates one content type from the selected GitHub and Linear integrations. Set at least one in targets.repositoryIds or targets.linearIntegrationIds. Times are in UTC. A schedule with the same source, targets, output, and lookback settings as an existing one is rejected with 409.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Display name shown in the dashboard.","example":"Weekly changelog"},"sourceType":{"type":"string","enum":["cron"],"description":"Always cron for schedules."},"sourceConfig":{"type":"object","properties":{"cron":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","custom"],"description":"How often the schedule runs.","example":"weekly"},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day to run, in UTC (0-23).","example":9},"minute":{"type":"integer","minimum":0,"maximum":59,"description":"Minute of the hour to run (0-59).","example":0},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"Day of the week for weekly schedules, 0 (Sunday) to 6 (Saturday). Required when frequency is weekly.","example":1},"dayOfMonth":{"type":"integer","minimum":1,"maximum":31,"description":"Day of the month for monthly schedules (1-31). Required when frequency is monthly.","example":1},"intervalDays":{"type":"integer","minimum":2,"maximum":90,"description":"Run every N days (2-90). Required when frequency is custom.","example":3},"anchorDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC calendar date (YYYY-MM-DD) a custom interval counts from. Defaults to today.","example":"2026-09-03"}},"required":["frequency","hour","minute"]}},"required":["cron"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"default":[],"description":"GitHub integration IDs to generate from, as returned in the github array of GET /v1/integrations. Defaults to none when linearIntegrationIds is set.","example":["51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"]},"linearIntegrationIds":{"type":"array","items":{"type":"string","minLength":1},"description":"Linear integration IDs to generate from, as returned in the linear array of GET /v1/integrations. When omitted, runs read every enabled Linear integration; send [] to read none.","example":["7f9a2b3c-1d4e-4f5a-9b6c-8d7e6f5a4b3c"]}},"description":"Data sources each run reads from. Set at least one GitHub or Linear integration."},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"],"description":"Type of content each run generates.","example":"changelog"},"outputConfig":{"type":"object","properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"],"description":"Where auto-published posts are sent."},"brandVoiceId":{"type":"string","minLength":1,"description":"Brand identity ID to write in. Defaults to the organization's default brand identity.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"instructions":{"type":"string","minLength":1,"maxLength":2000,"description":"Free-text brief for this schedule, passed to the writer on every run on top of the brand's custom instructions. Use it to steer the angle of the content, for example tutorial-style blog posts.","example":"Write a tutorial-style post that walks through one feature shipped in this window, with code samples."},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"],"description":"Where to announce new content after a successful run: Slack posts to the organization's notification channel, email goes to the workspace owners.","example":{"slack":true,"email":false}}}},"enabled":{"type":"boolean","description":"Whether the schedule runs. Disabled schedules are stored but never fire.","example":true},"autoPublish":{"type":"boolean","default":false,"description":"Publish generated posts automatically instead of saving them as drafts.","example":false},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"],"default":"last_7_days","description":"How far back each run collects source activity.","example":"last_7_days"}},"required":["name","sourceType","sourceConfig","targets","outputType","enabled"]}}}},"responses":{"201":{"description":"Schedule created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"sourceType":{"type":"string","enum":["cron"]},"sourceConfig":{"type":"object","properties":{"cron":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","custom"],"description":"How often the schedule runs.","example":"weekly"},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day to run, in UTC (0-23).","example":9},"minute":{"type":"integer","minimum":0,"maximum":59,"description":"Minute of the hour to run (0-59).","example":0},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"Day of the week for weekly schedules, 0 (Sunday) to 6 (Saturday). Required when frequency is weekly.","example":1},"dayOfMonth":{"type":"integer","minimum":1,"maximum":31,"description":"Day of the month for monthly schedules (1-31). Required when frequency is monthly.","example":1},"intervalDays":{"type":"integer","minimum":2,"maximum":90,"description":"Run every N days (2-90). Required when frequency is custom.","example":3},"anchorDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC calendar date (YYYY-MM-DD) a custom interval counts from. Defaults to today.","example":"2026-09-03"}},"required":["frequency","hour","minute"]}},"required":["cron"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string"},"description":"GitHub integration IDs to generate from, as returned in the github array of GET /v1/integrations."},"linearIntegrationIds":{"type":"array","items":{"type":"string"},"description":"Linear integration IDs to generate from, as returned in the linear array of GET /v1/integrations. When omitted, runs read every enabled Linear integration; send [] to read none."}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"],"description":"Where auto-published posts are sent."},"brandVoiceId":{"type":"string","minLength":1,"description":"Brand identity ID to write in. Defaults to the organization's default brand identity.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"instructions":{"type":"string","minLength":1,"maxLength":2000,"description":"Free-text brief for this schedule, passed to the writer on every run on top of the brand's custom instructions. Use it to steer the angle of the content, for example tutorial-style blog posts.","example":"Write a tutorial-style post that walks through one feature shipped in this window, with code samples."},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"],"description":"Where to announce new content after a successful run: Slack posts to the organization's notification channel, email goes to the workspace owners.","example":{"slack":true,"email":false}}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"]}},"required":["id","organizationId","name","sourceType","sourceConfig","targets","outputType","enabled","autoPublish","createdAt","updatedAt","lookbackWindow"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["schedule","organization"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to create schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/schedules/{scheduleId}":{"patch":{"tags":["Schedules"],"operationId":"updateSchedule","summary":"Update a schedule","description":"Updates only the fields you send; everything else keeps its current value. targets and outputConfig merge field by field, sourceConfig.cron is replaced as a whole, and null clears an outputConfig field. The updated schedule is validated like a new one, so it must keep at least one GitHub or Linear integration.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"sched_123"},"required":true,"in":"path","name":"scheduleId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchScheduleRequest"}}}},"responses":{"200":{"description":"Schedule updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"schedule":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"sourceType":{"type":"string","enum":["cron"]},"sourceConfig":{"type":"object","properties":{"cron":{"type":"object","properties":{"frequency":{"type":"string","enum":["daily","weekly","monthly","custom"],"description":"How often the schedule runs.","example":"weekly"},"hour":{"type":"integer","minimum":0,"maximum":23,"description":"Hour of the day to run, in UTC (0-23).","example":9},"minute":{"type":"integer","minimum":0,"maximum":59,"description":"Minute of the hour to run (0-59).","example":0},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"Day of the week for weekly schedules, 0 (Sunday) to 6 (Saturday). Required when frequency is weekly.","example":1},"dayOfMonth":{"type":"integer","minimum":1,"maximum":31,"description":"Day of the month for monthly schedules (1-31). Required when frequency is monthly.","example":1},"intervalDays":{"type":"integer","minimum":2,"maximum":90,"description":"Run every N days (2-90). Required when frequency is custom.","example":3},"anchorDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"UTC calendar date (YYYY-MM-DD) a custom interval counts from. Defaults to today.","example":"2026-09-03"}},"required":["frequency","hour","minute"]}},"required":["cron"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string"},"description":"GitHub integration IDs to generate from, as returned in the github array of GET /v1/integrations."},"linearIntegrationIds":{"type":"array","items":{"type":"string"},"description":"Linear integration IDs to generate from, as returned in the linear array of GET /v1/integrations. When omitted, runs read every enabled Linear integration; send [] to read none."}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"],"description":"Where auto-published posts are sent."},"brandVoiceId":{"type":"string","minLength":1,"description":"Brand identity ID to write in. Defaults to the organization's default brand identity.","example":"51c2f3aa-efdd-4e28-8e69-23fa2dfd3561"},"instructions":{"type":"string","minLength":1,"maxLength":2000,"description":"Free-text brief for this schedule, passed to the writer on every run on top of the brand's custom instructions. Use it to steer the angle of the content, for example tutorial-style blog posts.","example":"Write a tutorial-style post that walks through one feature shipped in this window, with code samples."},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"],"description":"Where to announce new content after a successful run: Slack posts to the organization's notification channel, email goes to the workspace owners.","example":{"slack":true,"email":false}}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"lookbackWindow":{"type":"string","enum":["current_day","yesterday","last_7_days","last_14_days","last_30_days"]}},"required":["id","organizationId","name","sourceType","sourceConfig","targets","outputType","enabled","autoPublish","createdAt","updatedAt","lookbackWindow"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["schedule","organization"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Schedule or organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to update schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Schedules"],"operationId":"deleteSchedule","summary":"Delete a schedule","description":"Deletes the schedule and stops future runs. Posts generated by earlier runs are kept.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"sched_123"},"required":true,"in":"path","name":"scheduleId"}],"responses":{"200":{"description":"Schedule deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","organization"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Schedule or organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to delete schedule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/schedules/{scheduleId}/run":{"post":{"tags":["Schedules"],"operationId":"runSchedule","summary":"Run a schedule now","description":"Starts one run of an enabled schedule right away, outside its cron timing, as the dashboard's Run now does. Returns 202 with the run's ID; follow it with `GET /v1/schedules/{scheduleId}/runs` until its status leaves `running`. Disabled schedules return 400.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"sched_123"},"required":true,"in":"path","name":"scheduleId"}],"responses":{"202":{"description":"Schedule run started","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","description":"ID of the run, as listed by `GET /v1/schedules/{scheduleId}/runs`."},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["runId","organization"]}}}},"400":{"description":"Schedule is disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Failed to start the schedule run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/schedules/{scheduleId}/runs":{"get":{"tags":["Schedules"],"operationId":"listScheduleRuns","summary":"List a schedule's runs","description":"Returns the schedule's most recent runs, newest first, with their status and the draft post each run created.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"sched_123"},"required":true,"in":"path","name":"scheduleId"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Schedule runs fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","success","failed","skipped"],"description":"`running` until the run reports back. A run that never reports back is shown as `failed` after six hours."},"title":{"type":["string","null"],"description":"Title of what the run produced, null while running."},"postId":{"type":["string","null"],"description":"The draft post the run created, if any."},"errorMessage":{"type":["string","null"]},"manual":{"type":"boolean","description":"Started on demand rather than by the schedule."},"startedAt":{"type":"string"},"finishedAt":{"type":["string","null"]}},"required":["id","status","title","postId","errorMessage","manual","startedAt","finishedAt"]}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["runs","organization"]}}}},"400":{"description":"Invalid query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Schedule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to list schedule runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/event-triggers":{"get":{"tags":["Event Triggers"],"operationId":"listEventTriggers","summary":"List event triggers","parameters":[{"schema":{"type":"string","description":"Filter by repository IDs using a comma-separated list","example":"repo_123,repo_456"},"required":false,"description":"Filter by repository IDs using a comma-separated list","name":"repositoryIds","in":"query"}],"responses":{"200":{"description":"Event triggers fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"eventTriggers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"sourceType":{"type":"string","enum":["github_webhook"]},"sourceConfig":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"string","enum":["release","push"]},"minItems":1},"includePreReleases":{"type":"boolean","default":true},"ignoreCommitPatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"default":[]}},"required":["eventTypes"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"]},"brandVoiceId":{"type":"string","minLength":1},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"]}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","name","sourceType","sourceConfig","targets","outputType","enabled","autoPublish","createdAt","updatedAt"]}},"repositoryMap":{"type":"object","additionalProperties":{"type":"string"}},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["eventTriggers","repositoryMap","organization"]}}}},"400":{"description":"Invalid query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to list event triggers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Event Triggers"],"operationId":"createEventTrigger","summary":"Create an event trigger","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceType":{"type":"string","enum":["github_webhook"]},"sourceConfig":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"string","enum":["release","push"]},"minItems":1},"includePreReleases":{"type":"boolean","default":true},"ignoreCommitPatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"default":[]}},"required":["eventTypes"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":"object","properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"]},"brandVoiceId":{"type":"string","minLength":1},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"]}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean","default":false}},"required":["sourceType","sourceConfig","targets","outputType","enabled"]}}}},"responses":{"201":{"description":"Event trigger created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"eventTrigger":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"sourceType":{"type":"string","enum":["github_webhook"]},"sourceConfig":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"string","enum":["release","push"]},"minItems":1},"includePreReleases":{"type":"boolean","default":true},"ignoreCommitPatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"default":[]}},"required":["eventTypes"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"]},"brandVoiceId":{"type":"string","minLength":1},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"]}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","name","sourceType","sourceConfig","targets","outputType","enabled","autoPublish","createdAt","updatedAt"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["eventTrigger","organization"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate event trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to create event trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/event-triggers/{triggerId}":{"get":{"tags":["Event Triggers"],"operationId":"getEventTrigger","summary":"Get an event trigger","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"trig_123"},"required":true,"in":"path","name":"triggerId"}],"responses":{"200":{"description":"Event trigger fetched successfully","content":{"application/json":{"schema":{"type":"object","properties":{"eventTrigger":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"sourceType":{"type":"string","enum":["github_webhook"]},"sourceConfig":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"string","enum":["release","push"]},"minItems":1},"includePreReleases":{"type":"boolean","default":true},"ignoreCommitPatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"default":[]}},"required":["eventTypes"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"]},"brandVoiceId":{"type":"string","minLength":1},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"]}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","name","sourceType","sourceConfig","targets","outputType","enabled","autoPublish","createdAt","updatedAt"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["eventTrigger","organization"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Event trigger or organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to fetch event trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Event Triggers"],"operationId":"updateEventTrigger","summary":"Update an event trigger","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"trig_123"},"required":true,"in":"path","name":"triggerId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchEventTriggerRequest"}}}},"responses":{"200":{"description":"Event trigger updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"eventTrigger":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string"},"name":{"type":"string"},"sourceType":{"type":"string","enum":["github_webhook"]},"sourceConfig":{"type":"object","properties":{"eventTypes":{"type":"array","items":{"type":"string","enum":["release","push"]},"minItems":1},"includePreReleases":{"type":"boolean","default":true},"ignoreCommitPatterns":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":10,"default":[]}},"required":["eventTypes"]},"targets":{"type":"object","properties":{"repositoryIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1}},"required":["repositoryIds"]},"outputType":{"type":"string","enum":["changelog","blog_post","linkedin_post","twitter_post","image"]},"outputConfig":{"type":["object","null"],"properties":{"publishDestination":{"type":"string","enum":["webflow","framer","custom"]},"brandVoiceId":{"type":"string","minLength":1},"notify":{"type":"object","properties":{"slack":{"type":"boolean"},"email":{"type":"boolean"}},"required":["slack","email"]}}},"enabled":{"type":"boolean"},"autoPublish":{"type":"boolean"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","organizationId","name","sourceType","sourceConfig","targets","outputType","enabled","autoPublish","createdAt","updatedAt"]},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["eventTrigger","organization"]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Event trigger or organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Duplicate event trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to update event trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Event Triggers"],"operationId":"deleteEventTrigger","summary":"Delete an event trigger","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"trig_123"},"required":true,"in":"path","name":"triggerId"}],"responses":{"200":{"description":"Event trigger deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"organization":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"logo":{"type":["string","null"]}},"required":["id","slug","name","logo"]}},"required":["id","organization"]}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Event trigger or organization not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to delete event trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chats":{"get":{"tags":["Chats"],"operationId":"listChats","summary":"List chats","description":"Returns the organization's chat sessions without their messages. Use GET /v1/chats/{chatId} to load a conversation.","responses":{"200":{"description":"Chats fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetChatsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Chats"],"operationId":"createChat","summary":"Start a new chat and stream the reply","description":"Creates a chat session, sends the first message, and streams the assistant reply. Read the X-Chat-Id response header to continue the conversation with POST /v1/chats/{chatId}.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendChatMessageRequest"}}}},"responses":{"200":{"description":"Streaming UI message stream (newline-delimited JSON chunks). Read the `X-Chat-Id` response header for the chat id, or take it from the `start` chunk's `messageMetadata.chatId`.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or usage limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Chat not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat is generating or pending approvals have changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 30 requests per 1 minute per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Failed to process chat request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chats/by-external":{"get":{"tags":["Chats"],"operationId":"getChatByExternalChannel","summary":"Get a chat by external channel id","description":"Looks up the chat session linked to a Discord or Slack channel, or tagged with a dashboard id. Link a chat by passing externalChannelId when you create it.","parameters":[{"schema":{"type":"string","enum":["discord","slack","dashboard"],"description":"Source the chat was linked with: a messaging platform, or dashboard for your own id.","example":"discord"},"required":true,"description":"Source the chat was linked with: a messaging platform, or dashboard for your own id.","name":"source","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Channel ID on that platform, or the id you tagged the chat with.","example":"channel_123"},"required":true,"description":"Channel ID on that platform, or the id you tagged the chat with.","name":"id","in":"query"}],"responses":{"200":{"description":"Chat fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatSessionSummary"}}}},"400":{"description":"Invalid query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Chat not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chats/{chatId}":{"get":{"tags":["Chats"],"operationId":"getChat","summary":"Get a single chat with messages","description":"Returns the chat session and its full message history in UI message format.","parameters":[{"schema":{"type":"string","minLength":1,"example":"chat_abc123"},"required":true,"name":"chatId","in":"path"}],"responses":{"200":{"description":"Chat fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetChatResponse"}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Chat not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Chats"],"operationId":"postChatMessage","summary":"Post a message to an existing chat and stream the reply","description":"Sends a message or resumes pending tool approvals and streams the assistant reply. Earlier messages are included automatically. To approve or deny tools, send approvals: [{ \"id\": \"<approvalId>\", \"approved\": true }] for every pending approval in the latest assistant message, without a message field; use \"approved\": false to deny. Approval IDs are emitted in tool-approval-request chunks and stored on tool parts in chat history.","parameters":[{"schema":{"type":"string","minLength":1,"example":"chat_abc123"},"required":true,"name":"chatId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendChatMessageRequest"}}}},"responses":{"200":{"description":"Streaming UI message stream (newline-delimited JSON chunks). Read the `X-Chat-Id` response header for the chat id, or take it from the `start` chunk's `messageMetadata.chatId`.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or usage limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Chat not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Chat is generating or pending approvals have changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 30 requests per 1 minute per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Failed to process chat request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/skills":{"get":{"tags":["Skills"],"operationId":"listSkills","summary":"List skills","description":"Returns the organization's skills sorted by name, including built-in system skills (isSystem: true). Skill content is omitted; use GET /v1/skills/{name} to read it.","responses":{"200":{"description":"Skills fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSkillsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Skills"],"operationId":"createSkill","summary":"Create a skill","description":"Creates a custom skill. Names must be unique within the organization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillRequest"}}}},"responses":{"201":{"description":"Skill created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkillResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Skill name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/skills/{name}":{"get":{"tags":["Skills"],"operationId":"getSkill","summary":"Get a single skill","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Skill name. Lowercase letters, digits, and hyphens only.","example":"humanizer"},"required":true,"description":"Skill name. Lowercase letters, digits, and hyphens only.","name":"name","in":"path"}],"responses":{"200":{"description":"Skill fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillResponse"}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Skills"],"operationId":"patchSkill","summary":"Update a skill","description":"Updates the name, description, or content of a skill. System skills can be edited but not renamed.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Skill name. Lowercase letters, digits, and hyphens only.","example":"humanizer"},"required":true,"description":"Skill name. Lowercase letters, digits, and hyphens only.","name":"name","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSkillRequest"}}}},"responses":{"200":{"description":"Skill updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSkillResponse"}}}},"400":{"description":"Invalid path params or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or attempt to rename a system skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Skill name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Skills"],"operationId":"deleteSkill","summary":"Delete a skill","description":"Deletes a custom skill. System skills cannot be deleted.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$","description":"Skill name. Lowercase letters, digits, and hyphens only.","example":"humanizer"},"required":true,"description":"Skill name. Lowercase letters, digits, and hyphens only.","name":"name","in":"path"}],"responses":{"200":{"description":"Skill deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSkillResponse"}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or attempt to delete a system skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/me/workspaces":{"get":{"tags":["Discovery"],"operationId":"getWorkspaces","summary":"Get authenticated workspace context","description":"Returns the current workspace and authentication details. OAuth users and account-wide API keys also receive their accepted memberships and can opt into pending invitations; single-organization API keys only receive their current workspace. Discovery does not change the workspace bound to the bearer token.","parameters":[{"schema":{"type":"string","enum":["true"]},"required":false,"name":"includePending","in":"query"}],"responses":{"200":{"description":"Workspace context fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetWorkspacesResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Bearer token is not scoped to an organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Current workspace not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/{organizationSlug}":{"post":{"tags":["Feedback"],"operationId":"submitOrganizationFeedback","summary":"Submit feedback to an organization's feedback URL","description":"Record feedback from an AI agent or integration by posting to the organization's feedback URL, as shown on the Feedback page in the dashboard. No credentials are required. Limited per source IP and per organization.","security":[],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":63,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i","description":"Your organization slug, as shown in your feedback URL on the Feedback page.","example":"acme"},"required":true,"description":"Your organization slug, as shown in your feedback URL on the Feedback page.","in":"path","name":"organizationSlug"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitFeedbackRequest"}}}},"responses":{"202":{"description":"Feedback accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitFeedbackResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"AI traffic event limit reached for this billing period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Feedback endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"This idempotencyKey was already used for different feedback","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 30 requests per 10 minutes per IP address, plus 200 requests per hour per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}}}}},"/v1/feedback":{"post":{"tags":["Feedback"],"operationId":"submitFeedback","summary":"Submit feedback with an API key","description":"Record feedback for the organization that owns the credential. Requires an API key with the feedback.write scope. Agents and MCP servers should post to the organization's feedback URL instead.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitFeedbackRequest"}}}},"responses":{"202":{"description":"Feedback accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitFeedbackResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"AI traffic event limit reached for this billing period","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"This idempotencyKey was already used for different feedback","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 120 requests per 1 minute per API key.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Feedback"],"operationId":"listFeedback","summary":"List feedback","parameters":[{"schema":{"type":"string","enum":["new","triaged","resolved","archived"],"description":"Triage status.","example":"new"},"required":false,"description":"Triage status.","name":"status","in":"query"},{"schema":{"type":"string","enum":["bug","feature","praise","question","other"],"description":"What kind of feedback this is.","example":"bug"},"required":false,"description":"What kind of feedback this is.","name":"kind","in":"query"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":false,"name":"projectId","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Items per page","example":25},"required":false,"description":"Items per page","name":"limit","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number","example":1},"required":false,"description":"Page number","name":"page","in":"query"}],"responses":{"200":{"description":"Feedback fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListFeedbackResponse"}}}},"400":{"description":"Invalid query params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/feedback/{feedbackId}":{"get":{"tags":["Feedback"],"operationId":"getFeedback","summary":"Get a single feedback entry","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"fb_123"},"required":true,"in":"path","name":"feedbackId"}],"responses":{"200":{"description":"Feedback fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"400":{"description":"Invalid path params","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Feedback not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Feedback"],"operationId":"updateFeedback","summary":"Update feedback status","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"fb_123"},"required":true,"in":"path","name":"feedbackId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFeedbackRequest"}}}},"responses":{"200":{"description":"Feedback updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackResponse"}}}},"400":{"description":"Invalid path params or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Feedback not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects":{"get":{"tags":["GEO"],"operationId":"listProjects","summary":"List GEO projects","responses":{"200":{"description":"Projects fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoProjectsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["GEO"],"operationId":"createProject","summary":"Create a GEO project","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGeoProjectRequest"}}}},"responses":{"201":{"description":"Project created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoProjectResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}":{"get":{"tags":["GEO"],"operationId":"getProject","summary":"Get a single GEO project","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Project fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoProjectResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["GEO"],"operationId":"updateProject","summary":"Rename a GEO project or relink its brand identity","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchGeoProjectRequest"}}}},"responses":{"200":{"description":"Project updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoProjectResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["GEO"],"operationId":"deleteProject","summary":"Delete a GEO project and all of its GEO data","description":"Cascades to the project's GEO settings, prompts, sequences, competitors, scans, checks and reports, and cancels any pending scheduled scan. Agent feedback is kept but detached. The organization's last project cannot be deleted. Projects with hosted Sites cannot be deleted; delete their Sites first.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Project deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteGeoProjectResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/settings":{"get":{"tags":["GEO"],"operationId":"getGeoSettings","summary":"Get a project's GEO settings","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Settings fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoSettingsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["GEO"],"operationId":"updateGeoSettings","summary":"Replace a project's GEO settings","description":"Writes the full settings document and re-arms the recurring scan. Engines must be ids returned by `GET /projects/{projectId}/geo/engines` (model APIs plus consumer surfaces such as `google/ai-overview`, `google/gemini` and `openai/chatgpt`) and languages must be supported languages; an unknown value is rejected with a 400 instead of being replaced by a default. Zero data retention is forced off without the ZDR add-on, and engines that are not visible to this caller keep their stored selection. Competitors are managed through the competitors endpoints and are not part of this payload. The language the project's prompts are written in always stays tracked: leaving it out of `languages` adds it back as the first entry, and a full list without it is rejected with a 400.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchGeoSettingsRequest"}}}},"responses":{"200":{"description":"Settings updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoSettingsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/engines":{"get":{"tags":["GEO"],"operationId":"listGeoEngines","summary":"List the answer engines a project can track","description":"Returns every engine id this organization can select in `engines` when updating GEO settings. This includes model APIs and consumer surfaces scanned through hosted browsers, such as `google/ai-overview` (Google AI Overview), `google/gemini` (the Gemini app) and `openai/chatgpt` (the ChatGPT app). Legacy engines that a project already tracks stay accepted but are not listed.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Engines fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoEngineListResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/prompts":{"get":{"tags":["GEO"],"operationId":"listGeoPrompts","summary":"List tracked GEO prompts","description":"Returns custom prompts alongside the prompts derived automatically from the project's brand context.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Prompts fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoPromptsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["GEO"],"operationId":"createGeoPrompt","summary":"Track a new GEO prompt","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGeoPromptRequest"}}}},"responses":{"201":{"description":"Prompt created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPromptResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/prompts/{promptId}":{"patch":{"tags":["GEO"],"operationId":"updateGeoPrompt","summary":"Update a tracked GEO prompt","description":"Enable or disable a tracked prompt, or replace tags on a custom prompt.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"promptId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchGeoPromptRequest"}}}},"responses":{"200":{"description":"Prompt updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPromptResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["GEO"],"operationId":"deleteGeoPrompt","summary":"Stop tracking a GEO prompt","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"promptId","in":"path"}],"responses":{"200":{"description":"Prompt deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteGeoPromptResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/prompts/import":{"post":{"tags":["GEO"],"operationId":"importGeoPrompts","summary":"Bulk import GEO prompts","description":"Accepts either structured `rows` or raw `csv` text. Prompts that already exist are skipped, not duplicated.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportGeoPromptsRequest"}}}},"responses":{"200":{"description":"Prompts imported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportGeoPromptsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/prompts/suggestions":{"get":{"tags":["GEO"],"operationId":"listGeoPromptSuggestions","summary":"List prompt suggestions","description":"Pending prompts Notra suggests tracking, derived from the project's Google Search Console queries. Empty until Search Console is connected and synced in the dashboard.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Prompt suggestions fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoPromptSuggestionsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/prompts/suggestions/{suggestionId}/accept":{"post":{"tags":["GEO"],"operationId":"acceptGeoPromptSuggestion","summary":"Accept a prompt suggestion","description":"Tracks the suggested prompt and returns it. When the project already tracks the same prompt, that prompt is returned instead of a duplicate. Returns 404 once the suggestion is no longer pending.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"suggestionId","in":"path"}],"responses":{"200":{"description":"Prompt suggestion accepted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPromptResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/prompts/suggestions/{suggestionId}/dismiss":{"post":{"tags":["GEO"],"operationId":"dismissGeoPromptSuggestion","summary":"Dismiss a prompt suggestion","description":"Removes the suggestion from the pending list without tracking it. Returns 404 once the suggestion is no longer pending.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"suggestionId","in":"path"}],"responses":{"200":{"description":"Prompt suggestion dismissed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DismissGeoPromptSuggestionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/sequences":{"get":{"tags":["GEO"],"operationId":"listGeoSequences","summary":"List GEO prompt sequences","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Sequences fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoSequencesResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["GEO"],"operationId":"createGeoSequence","summary":"Create a GEO prompt sequence","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGeoSequenceRequest"}}}},"responses":{"201":{"description":"Sequence created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoSequenceResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/sequences/{sequenceId}":{"patch":{"tags":["GEO"],"operationId":"updateGeoSequence","summary":"Update a GEO prompt sequence","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"sequenceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchGeoSequenceRequest"}}}},"responses":{"200":{"description":"Sequence updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoSequenceResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["GEO"],"operationId":"deleteGeoSequence","summary":"Delete a GEO prompt sequence","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"sequenceId","in":"path"}],"responses":{"200":{"description":"Sequence deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteGeoSequenceResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/sequences/{sequenceId}/run":{"post":{"tags":["GEO"],"operationId":"runGeoSequence","summary":"Run a GEO prompt sequence now","description":"Runs the sequence now. API-based answer engines run synchronously: the request stays open while every turn plays against each of them, which can take several minutes, and `checks`, `mentions` and `engines` report their result. Tracked consumer apps (ChatGPT, Perplexity, Gemini, AI Mode, Copilot) answer far more slowly, so they are queued as a background scan instead: `queuedScanId` names it and `queuedEngines` lists the apps it covers. Poll `GET /v1/projects/{projectId}/geo/scans/{scanId}` for that part. A run with only consumer apps answers right away with `checks: 0`. Runs also work while automatic scans are paused. Use a client timeout of at least five minutes; after four minutes the API stops waiting and answers 409 while the run finishes on its own. Do not retry; read the result from the project's GEO checks. The work happens inside the Notra dashboard, which owns the model credentials and billing gates; the public API never calls an answer engine itself. Results also land in the project's GEO checks.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"sequenceId","in":"path"}],"responses":{"200":{"description":"API-based engines finished; a queued consumer-app scan is named by queuedScanId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunGeoSequenceResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Sequence execution is still running after the internal timeout; do not retry the run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas":{"get":{"tags":["GEO"],"operationId":"listGeoPersonas","summary":"List GEO personas","description":"Buyer personas that hold multi-turn conversations with the answer engines, each with its profile, memories and conversation prompts. Archived personas are included with `archivedAt` set.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Personas fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoPersonasResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas/{personaId}":{"patch":{"tags":["GEO"],"operationId":"updateGeoPersona","summary":"Update a GEO persona","description":"Turns a persona on or off for scheduled scans, or edits its details. Editing details clears its conversation prompts, so call `POST …/personas/generate` with `personaId` and `promptsOnly: true` before running it again. Archived personas must be restored first.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"personaId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchGeoPersonaRequest"}}}},"responses":{"200":{"description":"Persona updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPersonaResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["GEO"],"operationId":"archiveGeoPersona","summary":"Archive a GEO persona","description":"Archives and disables the persona. Its past results stay readable, and it can be restored.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"personaId","in":"path"}],"responses":{"200":{"description":"Persona archived successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveGeoPersonaResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas/{personaId}/restore":{"post":{"tags":["GEO"],"operationId":"restoreGeoPersona","summary":"Restore an archived GEO persona","description":"Restores the persona as disabled. Fails with 400 when the project already has the maximum number of active personas.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"personaId","in":"path"}],"responses":{"200":{"description":"Persona restored successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPersonaResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas/{personaId}/results":{"get":{"tags":["GEO"],"operationId":"getGeoPersonaResults","summary":"Get a GEO persona's conversation results","description":"Every turn of one scan's persona conversations, per engine: the prompt, the answer, whether the brand was mentioned, its position, and the sources the engine cited. `scans` lists the scans that played this persona, newest first.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"personaId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Scan to read. Defaults to the latest scan that played this persona; ids are listed in `scans`."},"required":false,"description":"Scan to read. Defaults to the latest scan that played this persona; ids are listed in `scans`.","name":"scanId","in":"query"}],"responses":{"200":{"description":"Persona results fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPersonaResultsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas/activity":{"get":{"tags":["GEO"],"operationId":"getGeoPersonaActivity","summary":"Get GEO persona activity","description":"Daily checks and mentions per persona and persona version. Defaults to the last 30 days.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Persona activity fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPersonaActivityResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas/{personaId}/run":{"post":{"tags":["GEO"],"operationId":"runGeoPersona","summary":"Run a GEO persona now","description":"Plays the persona's conversation now and uses AI credits at twice the rate of a single prompt check. API-based answer engines run synchronously, so the request can stay open for several minutes; `checks`, `mentions` and `engines` report their result. Tracked consumer apps are queued as a background scan named by `queuedScanId`; poll `GET /v1/projects/{projectId}/geo/scans/{scanId}` for that part. Use a client timeout of at least five minutes. After four minutes the API answers 409 while the run finishes on its own; do not retry, read `GET …/personas/{personaId}/results` instead.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"personaId","in":"path"}],"responses":{"200":{"description":"API-based engines finished; a queued consumer-app scan is named by queuedScanId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunGeoPersonaResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Persona run is still running after the internal timeout; do not retry the run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas/generate":{"post":{"tags":["GEO"],"operationId":"generateGeoPersonas","summary":"Generate GEO personas","description":"Starts AI persona generation in the background and uses AI credits. With no body it creates a full set from the project's brand, prompts and competitors; `brief` adds one persona; `personaId` regenerates one in place (with `promptsOnly`, only its conversation prompts). Only one job runs per project: while one is running, this returns that job instead of starting another. Poll `GET /v1/projects/{projectId}/geo/personas/generation` until `status` is `completed` or `failed`, then list the personas.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateGeoPersonasRequest"}}}},"responses":{"202":{"description":"Generation job queued or already running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPersonaGenerationResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 5 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/personas/generation":{"get":{"tags":["GEO"],"operationId":"getGeoPersonaGeneration","summary":"Get the GEO persona generation status","description":"The project's latest persona generation job. A job that never started within a few minutes is reported as `failed`.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Generation status fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPersonaGenerationResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 5 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/competitors":{"get":{"tags":["GEO"],"operationId":"listGeoCompetitors","summary":"List tracked GEO competitors","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Competitors fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoCompetitorsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"tags":["GEO"],"operationId":"upsertGeoCompetitor","summary":"Create or update a tracked GEO competitor","description":"Matches on name, case-insensitively. Send `previousName` to rename an existing competitor. Returns the full competitor list.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PutGeoCompetitorRequest"}}}},"responses":{"200":{"description":"Competitor saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoCompetitorsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/competitors/suggestions":{"get":{"tags":["GEO"],"operationId":"suggestGeoCompetitors","summary":"Suggest GEO competitors for a domain","description":"Discovers likely competitors for a website. Results are cached per organization and domain.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Website domain, for example `example.com`.","example":"example.com"},"required":true,"description":"Website domain, for example `example.com`.","name":"domain","in":"query"}],"responses":{"200":{"description":"Competitor suggestions fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoCompetitorSuggestionsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/competitors/{name}":{"delete":{"tags":["GEO"],"operationId":"deleteGeoCompetitor","summary":"Stop tracking a GEO competitor","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Competitor name. Matched case-insensitively."},"required":true,"description":"Competitor name. Matched case-insensitively.","name":"name","in":"path"}],"responses":{"200":{"description":"Competitor deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoCompetitorsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/competitors/import":{"post":{"tags":["GEO"],"operationId":"importGeoCompetitors","summary":"Bulk import GEO competitors","description":"Accepts either structured `rows` or raw `csv` text. Existing competitors are updated in place rather than duplicated. One request takes a project's whole list (up to 2,000 competitors), so send it in a single call instead of splitting it.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportGeoCompetitorsRequest"}}}},"responses":{"200":{"description":"Competitors imported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportGeoCompetitorsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/scans":{"post":{"tags":["GEO"],"operationId":"createGeoScan","summary":"Trigger a GEO scan","description":"Queues a scan with the Notra dashboard, which owns the model credentials and billing gates. The public API never calls an answer engine itself. The scan record is created before the hand-off, so `scanId` is immediately readable via `GET /v1/projects/{projectId}/geo/scans/{scanId}`. Poll `statusUrl` (also returned as the `Location` header) until `status` leaves `running`. Returns 409 while a scan for this project is still in flight, and 402 when the plan or AI credits cannot cover a scan.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"202":{"description":"Scan accepted","headers":{"Location":{"description":"Relative path of the scan created for this trigger.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGeoScanResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 4 requests per 1 hour per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["GEO"],"operationId":"listGeoScans","summary":"List GEO scans","description":"Lists scans with planned, completed, mentioned, and explicitly failed check totals by engine. Failed scans include safe failure metadata when available.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1},"required":false,"name":"page","in":"query"}],"responses":{"200":{"description":"Scans fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoScansResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/scans/prompts/{promptId}":{"post":{"tags":["GEO"],"operationId":"createGeoPromptScan","summary":"Rescan a single GEO prompt","description":"Queues a scan of one enabled tracked prompt across the project's engines, for example to check a prompt again after publishing content for it. Only that prompt's checks run, so it costs less than a full scan. Otherwise it behaves like `POST /v1/projects/{projectId}/geo/scans`: poll `statusUrl` until `status` leaves `running`, 409 while another scan is in flight, 402 when the plan or AI credits cannot cover it, and it shares that route's rate limit. Returns 404 for a prompt that is unknown or disabled.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"promptId","in":"path"}],"responses":{"202":{"description":"Scan accepted","headers":{"Location":{"description":"Relative path of the scan created for this trigger.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGeoScanResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 4 requests per 1 hour per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/scans/{scanId}":{"get":{"tags":["GEO"],"operationId":"getGeoScan","summary":"Get a single GEO scan","description":"Returns scan status, check progress and mentions by engine, plus safe failure metadata for failed scans. Legacy scans without a saved plan report null planned totals.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"scanId","in":"path"}],"responses":{"200":{"description":"Scan fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoScanResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/overview":{"get":{"tags":["GEO"],"operationId":"getGeoVisibilityOverview","summary":"Get mention rates per engine","description":"Checks, mentions and average position for every answer engine the project tracks. Pass `days` for a rolling window, or `from`/`to` for an explicit one.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Overview fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityOverviewResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/timeseries":{"get":{"tags":["GEO"],"operationId":"getGeoVisibilityTimeseries","summary":"Get daily mention counts per engine","description":"One point per day and engine. Pass `days` for a rolling window, or `from`/`to` for an explicit one.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Timeseries fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityTimeseriesResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/prompt-results":{"get":{"tags":["GEO"],"operationId":"getGeoVisibilityPromptResults","summary":"Get the latest answer per prompt and engine","description":"The stored answer text, mention position, sentiment and grounding sources for each tracked prompt. Pass `days` for a rolling window, or `from`/`to` for an explicit one.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Prompt results fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityPromptResultsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/prompt-results/summaries":{"get":{"tags":["GEO"],"operationId":"listGeoPromptResultSummaries","summary":"List compact prompt result summaries","description":"A filtered, paginated projection of the latest answer per prompt and engine. Full answer text and sources are omitted; use checkId with the detail endpoint.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"engine","in":"query"},{"schema":{"type":"string","enum":["true","false"]},"required":false,"name":"mentioned","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":300},"required":false,"name":"query","in":"query"}],"responses":{"200":{"description":"Prompt result summaries fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityPromptResultSummariesResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/prompt-results/{checkId}":{"get":{"tags":["GEO"],"operationId":"getGeoPromptResultDetail","summary":"Get one full prompt result","description":"Loads the answer, grounding sources and token metadata for one checkId returned by the summaries or prompt-history endpoints.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"checkId","in":"path"}],"responses":{"200":{"description":"Prompt result fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityPromptResultDetailResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/competitor-share":{"get":{"tags":["GEO"],"operationId":"getGeoVisibilityCompetitorShare","summary":"Get share of voice across tracked brands","description":"Mention counts per brand with a per-brand trend, plus the daily timeseries behind it. Pass `days` for a rolling window, or `from`/`to` for an explicit one.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Competitor share fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityCompetitorShareResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/language-share":{"get":{"tags":["GEO"],"operationId":"getGeoVisibilityLanguageShare","summary":"Get mention rates per tracked language","description":"Checks, mentions and average position broken down by language. Only tracked prompts count, without sequences or personas. In a scan that ran several languages, a prompt counts only where the same engine also answered it in another language of that scan. Pass `days` for a rolling window, or `from`/`to` for an explicit one.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Language share fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityLanguageShareResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/visibility/competitors/{brand}":{"get":{"tags":["GEO"],"operationId":"getGeoVisibilityCompetitorDetail","summary":"Get one competitor's mention history","description":"Daily mentions and the prompts that produced them for a single brand. Without a window this falls back to the competitor-detail default rather than the project default, matching the dashboard.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Competitor brand name as reported by competitor-share."},"required":true,"description":"Competitor brand name as reported by competitor-share.","name":"brand","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Competitor detail fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoVisibilityCompetitorDetailResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/changes":{"get":{"tags":["GEO"],"operationId":"listGeoChanges","summary":"Compare the two latest GEO scans","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"GEO changes fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoChangesResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/prompts/{promptId}/history":{"get":{"tags":["GEO"],"operationId":"getGeoPromptHistory","summary":"Get the stored check history for one prompt","description":"Returns compact check rows. Use each check id with the prompt-result detail endpoint for the full answer.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"promptId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":false,"name":"scanId","in":"query"}],"responses":{"200":{"description":"Prompt history fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPromptHistoryResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/sentiment":{"get":{"tags":["GEO"],"operationId":"getGeoSentiment","summary":"Get aggregate GEO sentiment","description":"Returns current and previous-period sentiment metrics without starting billed analysis.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Sentiment fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoSentimentResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/sentiment/analysis":{"get":{"tags":["GEO"],"operationId":"getGeoSentimentAnalysis","summary":"Get the stored GEO sentiment analysis","description":"Reads the cached thematic analysis state and never starts a billed model run.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Sentiment analysis state fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoSentimentAnalysisResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/sentiment/evidence":{"get":{"tags":["GEO"],"operationId":"listGeoSentimentEvidence","summary":"List answers used as sentiment evidence","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"},{"schema":{"type":"string","maxLength":4096},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Sentiment evidence fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoSentimentEvidenceResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/shelf-sources":{"get":{"tags":["GEO"],"operationId":"listGeoShelfSources","summary":"List stored GEO shelf sources","description":"Returns a bounded page of cited and manually tracked sources, newest updates first.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":["integer","null"],"minimum":0,"maximum":100000,"default":0},"required":false,"name":"offset","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Shelf sources fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoShelfListResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/gaps":{"get":{"tags":["GEO"],"operationId":"listGeoContentGaps","summary":"List content gaps","description":"Prompts where competitors are mentioned and this brand is not, plus Search Console queries with no tracked prompt. Each row carries the brief already written for it, when there is one.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Gaps fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoContentGapsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/gaps/{promptId}":{"patch":{"tags":["GEO"],"operationId":"updateGeoContentGap","summary":"Ignore or restore a content gap","description":"Hides a prompt gap from `GET /v1/projects/{projectId}/geo/gaps` and from brief planning, or brings it back. `promptId` is the `id` of a row in `promptGaps`. Ignored gaps are not listed, so keep the id to restore one later. The id is not checked against the gap list.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"promptId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGeoContentGapRequest"}}}},"responses":{"200":{"description":"Content gap updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGeoContentGapResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/briefs":{"get":{"tags":["GEO"],"operationId":"listGeoContentBriefs","summary":"List content briefs","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Briefs fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGeoContentBriefsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["GEO"],"operationId":"planGeoContentBrief","summary":"Plan a content brief","description":"Researches the topic and writes a brief, then saves it as a draft article. This books AI credits and is billed. Planning happens inside Notra, which owns the model credentials. Set `autoApprove` to start the writer in the same call. When `sourceKind` and `sourceId` point at a gap that already has an open brief, that brief is returned instead of a new one being planned. If planning exceeds four minutes, the API returns 409 while work may still finish in Notra. Do not retry; list the project's GEO briefs to find the result.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGeoContentBriefRequest"}}}},"responses":{"200":{"description":"Brief planned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanGeoContentBriefResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Brief planning is still running after the internal timeout; do not retry the plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/briefs/{briefId}":{"get":{"tags":["GEO"],"operationId":"getGeoContentBrief","summary":"Get a single content brief","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"briefId","in":"path"}],"responses":{"200":{"description":"Brief fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoContentBriefResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["GEO"],"operationId":"updateGeoContentBrief","summary":"Update a content brief","description":"Edits the brief's outline and planning fields. Omitted fields keep their current value; list fields replace the whole list. Only briefs in `draft` or `failed` can be edited, and the draft post's plan is updated with them. Anything else returns 409. Editing drops research notes such as the baseline and recommended angle, as the dashboard editor does.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"briefId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGeoContentBriefRequest"}}}},"responses":{"200":{"description":"Brief updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoContentBriefResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/briefs/{briefId}/approve":{"post":{"tags":["GEO"],"operationId":"approveGeoContentBrief","summary":"Approve a brief and start the writer","description":"Claims the brief and queues the writer with the Notra dashboard. Only briefs in `draft` or `failed` can be approved; anything else returns 409.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$"},"required":true,"name":"briefId","in":"path"}],"responses":{"202":{"description":"Writer accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveGeoContentBriefResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 20 requests per 10 minutes per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/agent-readiness":{"get":{"tags":["GEO"],"operationId":"getGeoAgentReadiness","summary":"Get the latest agent readiness report","description":"The most recent completed report for the project's website, any newer run still in flight or failed, and the score history. Returns stored data only; it never starts a scan.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"200":{"description":"Report fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoAgentReadinessResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/agent-readiness/scan":{"post":{"tags":["GEO"],"operationId":"startGeoAgentReadinessScan","summary":"Start an agent readiness scan","description":"Queues a readiness scan for the project's website. A scan already running against the same URL is reused rather than duplicated, in which case `alreadyRunning` is true.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"}],"responses":{"202":{"description":"Scan accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoAgentReadinessScanResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 10 requests per 1 hour per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/traffic/overview":{"get":{"tags":["GEO"],"operationId":"getGeoTrafficOverview","summary":"Get AI traffic totals and sources","description":"Crawler and AI-referral visit totals, a per-source breakdown and the daily timeseries behind it.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Traffic overview fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoTrafficOverviewResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/traffic/log":{"get":{"tags":["GEO"],"operationId":"getGeoTrafficLog","summary":"Get recent AI traffic events","description":"The most recent individual requests from AI crawlers and referrals. This endpoint has no window; use `limit` to bound it. Pass `host` to keep the newest events for that hostname and its subdomains.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":200},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Comma-separated. One or more of: crawler, ai_referral."},"required":false,"description":"Comma-separated. One or more of: crawler, ai_referral.","name":"visitorTypes","in":"query"},{"schema":{"type":"string","description":"Comma-separated. One or more of: training-crawler, search-index, assistant-browse."},"required":false,"description":"Comma-separated. One or more of: training-crawler, search-index, assistant-browse.","name":"categories","in":"query"},{"schema":{"type":"string","maxLength":128,"description":"Hostname to filter on. Subdomains of this host are included. Omit for every host."},"required":false,"description":"Hostname to filter on. Subdomains of this host are included. Omit for every host.","name":"host","in":"query"}],"responses":{"200":{"description":"Traffic log fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoTrafficLogResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/traffic/journeys":{"get":{"tags":["GEO"],"operationId":"listGeoTrafficJourneys","summary":"List AI traffic journeys","description":"Sessions grouped by journey: how many pages one agent read, over what span, and a sample of the paths.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Journeys fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoTrafficJourneysResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/traffic/journeys/{journeyId}":{"get":{"tags":["GEO"],"operationId":"getGeoTrafficJourney","summary":"Get one journey's events","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128},"required":true,"name":"journeyId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"Journey fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoJourneyDetailResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/traffic/pages":{"get":{"tags":["GEO"],"operationId":"listGeoTrafficPages","summary":"List the most visited pages","description":"Which paths AI crawlers and referrals read most, with the previous window's count for comparison. Pass `host` to rank pages for that hostname and its subdomains before applying `limit`.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":500},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","enum":["crawler","ai_referral"]},"required":false,"name":"visitorType","in":"query"},{"schema":{"type":"string","maxLength":128,"description":"Hostname to filter on. Subdomains of this host are included. Omit for every host."},"required":false,"description":"Hostname to filter on. Subdomains of this host are included. Omit for every host.","name":"host","in":"query"}],"responses":{"200":{"description":"Pages fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoTrafficPagesResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/traffic/mcp":{"get":{"tags":["GEO"],"operationId":"getGeoMcpAnalytics","summary":"Get MCP server analytics","description":"Usage of your own MCP server, as reported by the `@usenotra/geo` SDK: request and error totals against the previous window, per-tool latency and errors, clients, models, intents, recent failures and tools that were never called. Captured arguments, responses and end-user IDs are not returned.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"MCP analytics fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoMcpAnalyticsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/projects/{projectId}/geo/traffic/mcp/tools/{toolName}":{"get":{"tags":["GEO"],"operationId":"getGeoMcpToolDetail","summary":"Get one MCP tool's analytics","description":"Which tools agents call right before and after this one, its failures grouped by message, and the intents it was called for.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","example":"b1f2c3d4-0000-4000-8000-000000000000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":128,"description":"Tool name as your MCP server registers it."},"required":true,"description":"Tool name as your MCP server registers it.","name":"toolName","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window size in days. Ignored when from/to are set."},"required":false,"description":"Rolling window size in days. Ignored when from/to are set.","name":"days","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-01-31"},"required":false,"name":"to","in":"query"}],"responses":{"200":{"description":"MCP tool analytics fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoMcpToolDetailResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/geo/ingest/setup":{"get":{"tags":["GEO"],"operationId":"getGeoIngestSetup","summary":"Get the install snippets","description":"The endpoint and framework snippets needed to send AI traffic to Notra. The snippets read the token from an environment variable; the token itself is issued by `POST /geo/ingest/token`, which requires a write scope.","responses":{"200":{"description":"Setup fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoIngestSetupResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/geo/ingest/token":{"post":{"tags":["GEO"],"operationId":"issueGeoIngestToken","summary":"Issue the tracking token","description":"Returns the current tracking token together with the install snippets. Pass `projectId` for a project-specific token; without it, the legacy token only accepts the organization's oldest project's hosts. Issuing does not invalidate previously issued tokens; use rotation for that.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"Bind the token to one project. Omit to track the whole organization."},"required":false,"description":"Bind the token to one project. Omit to track the whole organization.","name":"projectId","in":"query"}],"responses":{"200":{"description":"Token issued successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoIngestTokenResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/geo/ingest/rotate-token":{"post":{"tags":["GEO"],"operationId":"rotateGeoIngestToken","summary":"Rotate the tracking token","description":"Invalidates every tracking token previously issued for this organization and returns a fresh one. Deployments still sending the old token stop being accepted immediately.","parameters":[{"schema":{"type":"string","minLength":1,"pattern":"^[A-Za-z0-9_-]{1,100}$","description":"Bind the token to one project. Omit to track the whole organization."},"required":false,"description":"Bind the token to one project. Omit to track the whole organization.","name":"projectId","in":"query"}],"responses":{"200":{"description":"Token rotated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoIngestTokenResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"GEO plan or available AI credits required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Organization, project or resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Authentication or billing service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/eve/v1/session":{"post":{"tags":["Agent"],"operationId":"createAgentSession","summary":"Start a durable agent session","description":"The exact eve session protocol the Notra dashboard uses, proxied through API auth. Point any eve client (eve/client, useEveAgent) at /v2 as its host with your API key as a bearer token. Returns the session id and continuation token; stream events from GET /v2/eve/v1/session/{sessionId}/stream.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentSessionRequest"}}}},"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentSessionResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or usage limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 30 requests per 1 minute per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Failed to check usage limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Agent session creation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Agent service is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/eve/v1/session/{sessionId}":{"post":{"tags":["Agent"],"operationId":"sendAgentSessionMessage","summary":"Send a follow-up message or answer a pending input request","description":"Sends the next turn of an agent session. The server binds the session's stored continuation token, so the client-provided one is ignored. Answer input.requested events (tool approvals, questions) from the event stream via inputResponses.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAgentMessageRequest"}}}},"responses":{"200":{"description":"Upstream eve response with the next continuation token for this session.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or usage limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A message is already being processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 30 requests per 1 minute per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"500":{"description":"Failed to check usage limits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Agent service is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/eve/v1/session/{sessionId}/stream":{"get":{"tags":["Agent"],"operationId":"streamAgentSessionEvents","summary":"Stream an agent session's events","description":"Durable, replayable eve session event stream (newline-delimited JSON). Pass startIndex to resume from a known position. Includes input.requested events for tool approvals.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"sessionId","in":"path"}],"responses":{"200":{"description":"NDJSON event stream","content":{"application/x-ndjson":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or usage limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 30 requests per 1 minute per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Agent service is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/agent-chats":{"get":{"tags":["Agent"],"operationId":"listAgentChats","summary":"List agent sessions","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Agent sessions fetched successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAgentChatsResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden, or usage limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded. This endpoint allows 30 requests per 1 minute per organization.","headers":{"RateLimit-Limit":{"description":"Maximum requests allowed in the current window.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds the client should wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitErrorResponse"}}}},"503":{"description":"Agent service is not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{}}