{"openapi":"3.1.0","info":{"title":"Survey API","version":"1.0.0","description":"REST surface for getsurvey.dev. The agent-facing path is the MCP server at /api/mcp — see /docs/mcp.","license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://getsurvey.dev"}],"tags":[{"name":"projects","description":"Multi-project primitive"},{"name":"surveys","description":"Survey CRUD + publish"},{"name":"responses","description":"Response submit + read"},{"name":"billing","description":"Stripe-backed billing"},{"name":"members","description":"Project members + invites"},{"name":"system","description":"Health, install, agent prompt"}],"paths":{"/api/v1/projects":{"get":{"tags":["projects"],"summary":"List projects the caller is a member of","security":[{"ownerHeader":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["projects"],"summary":"Create a project (returns service key once)","security":[{"ownerHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string"},"publishableKey":{"type":"string"},"serviceKey":{"type":"string"},"dashboardUrl":{"type":"string"},"integrationSnippet":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/api/v1/projects/{projectId}":{"get":{"tags":["projects"],"summary":"Get project metadata + publishable key","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ownerHeader":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"project":{"type":"object"}}}}}}}}},"/api/v1/projects/{projectId}/stats":{"get":{"tags":["projects"],"summary":"Aggregate response stats over a window (range=7d|30d|90d)","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"range","in":"query","schema":{"type":"string","default":"30d"}}],"security":[{"ownerHeader":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"stats":{"type":"object"}}}}}}}}},"/api/v1/projects/{projectId}/activity":{"get":{"tags":["projects"],"summary":"Recent audit events (responses, edits, publishes, agent calls)","parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"security":[{"ownerHeader":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array"}}}}}}}}},"/api/v1/surveys":{"get":{"tags":["surveys"],"summary":"List surveys for a project","parameters":[{"name":"projectId","in":"query","required":true,"schema":{"type":"string"}}],"security":[{"ownerHeader":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"surveys":{"type":"array"}}}}}}}},"post":{"tags":["surveys"],"summary":"Create a draft survey","security":[{"ownerHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","draft"],"properties":{"projectId":{"type":"string"},"draft":{"type":"object","description":"SurveyDraft from @getsurvey/schema"}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"surveyId":{"type":"string"},"version":{"type":"integer"}}}}}}}}},"/api/v1/surveys/{surveyId}":{"get":{"tags":["surveys"],"summary":"Get a survey (latest for owner, published for SDK key)","parameters":[{"name":"surveyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"survey":{"type":"object"}}}}}}}},"patch":{"tags":["surveys"],"summary":"Save a new draft version","parameters":[{"name":"surveyId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ownerHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"surveyId":{"type":"string"},"version":{"type":"integer"}}}}}}}}},"/api/v1/surveys/{surveyId}/publish":{"post":{"tags":["surveys"],"summary":"Publish a survey version (defaults to latest)","parameters":[{"name":"surveyId","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"ownerHeader":[]}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"publishedVersion":{"type":"integer"},"publicUrl":{"type":"string"}}}}}}}}},"/api/v1/surveys/{surveyId}/summary":{"get":{"tags":["surveys"],"summary":"Token-efficient analytics — buckets, NPS, free-text clusters","parameters":[{"name":"surveyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object"}}}}}}}}},"/api/v1/surveys/parse":{"post":{"tags":["surveys"],"summary":"Parse loose JSON / markdown / prose into validated Question[]","security":[{"ownerHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["raw"],"properties":{"raw":{"type":"string","maxLength":50000},"format":{"type":"string","enum":["json","markdown","auto"]}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"questions":{"type":"array"},"warnings":{"type":"array"},"detectedFormat":{"type":"string"}}}}}}}}},"/api/v1/responses":{"post":{"tags":["responses"],"summary":"Submit a response (publishable key required)","security":[{"publishableKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["surveyId","surveyVersionId","answers","idempotencyKey"],"properties":{"surveyId":{"type":"string"},"surveyVersionId":{"type":"string"},"answers":{"type":"array"},"idempotencyKey":{"type":"string"},"respondentId":{"type":"string"},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"402":{"$ref":"#/components/responses/QuotaExceeded"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/health":{"get":{"tags":["system"],"summary":"Per-service configured + reachable status","responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"checks":{"type":"object"}}}}}}}}},"/install.md":{"get":{"tags":["system"],"summary":"Canonical install markdown (text/markdown)","responses":{"200":{"description":"Markdown blob"}}}},"/agent-prompt.md":{"get":{"tags":["system"],"summary":"Prompt to give an agent so it generates surveys conforming to our schema","responses":{"200":{"description":"Markdown blob"}}}}},"components":{"securitySchemes":{"ownerHeader":{"type":"apiKey","in":"header","name":"x-survey-owner","description":"Dashboard/dev mode. In production replaced by the Clerk session cookie."},"publishableKey":{"type":"apiKey","in":"header","name":"x-survey-key","description":"Project-scoped pk_... for SDK render-path calls."},"serviceKey":{"type":"http","scheme":"bearer","description":"Project-scoped sk_... for server-side reads + MCP."}},"responses":{"Unauthorized":{"description":"Missing or invalid auth"},"ServiceUnavailable":{"description":"Backing service not configured"},"QuotaExceeded":{"description":"Response quota exceeded for this project's plan"},"RateLimited":{"description":"Rate limit exceeded — see Retry-After"}}}}