Get started

The Succo AI Public API is a RESTful API for your surveys, forms and their responses. Authenticate with a bearer API key, read the contract below, then try any endpoint live in the API Reference — no builder, no dashboard required.

API Reference & playground →

Every endpoint, schema and response, with an inline “Try it” console.

MCP Server →

Let an AI client read your Succo data over the Model Context Protocol.

Requirements

All you need is a Succo AI account. Sign in, open account settings and create a Public API key — there is no separate developer account. Each key carries a fixed set of capability scopes and is pinned to an API version at creation time.

Authentication

The API uses bearer authentication. Send your key (succo_sk_…) in the Authorization header on every request:

curl https://succo.ai/api/public/v1/me \
  -H "Authorization: Bearer succo_sk_your_key_here"

Keys are scoped. A key only performs the actions its scopes allow; a call outside them is rejected. Scopes are shown on the key when you create it:

read read:pii write write:runs write:delete

Keep keys secret. Treat succo_sk_… like a password: never commit it, never ship it in frontend code. Rotate or revoke a key any time from account settings.

Base URL

All endpoints live under a single versioned base path:

https://succo.ai/api/public/v1

Versioning

The API is versioned by date. Pin a request to a version with the Succo-Version header; omit it and the request uses the version pinned onto your key. A version selects both the response shape and the accepted request payloads, so upgrades never break you silently.

curl https://succo.ai/api/public/v1/surveys \
  -H "Authorization: Bearer succo_sk_your_key_here" \
  -H "Succo-Version: 2026-07-21"

Version	Status
`2026-07-21`	active · default

Errors

Errors follow RFC 7807 and are returned as application/problem+json. Every error carries a stable, machine-readable code you can branch on — the human-readable detail may change, the code will not.

{
  "type": "https://succo.ai/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "No survey matches that id."
}

Pagination

List endpoints use keyset pagination with an opaque cursor. Responses are wrapped in an envelope; pass next_cursor back as ?cursor= to fetch the next page, and stop when it is null.

{
  "data": [ /* … */ ],
  "next_cursor": "eyJpZCI6…",
  "limit_left": 480
}

Trim the payload to just the fields you need with sparse fieldsets: append ?fields=id,title to any resource read.

PII & privacy

Personally identifiable information in responses is redacted by default. It is only returned when the key holds the read:pii scope and the request explicitly opts in with ?include_pii=true. This keeps ordinary integrations privacy-safe without extra work.

Ready? Open the API Reference, paste your key into the playground, and send your first request. Building an agent instead? Point it at llms.txt.