SpringRoll API reference

The OpenAPI 3.1 specification is available at /openapi.json and /api/openapi.yaml. Start at /api/v1 for the endpoint index and /api/v1/capabilities for tools and an example application manifest.

The MCP server card is at /.well-known/mcp/server-card.json. /llms.txt indexes the public documentation; /llms-full.txt contains selected complete references and a document index. Request a public page with Accept: text/markdown for its complete Markdown version.

For native platform APIs, set the API base to /api/connect/v1/{connector-slug} and keep the platform's own paths, methods, query parameters and body. Send the app environment's SpringRoll data token as the Bearer token. Owners approve native endpoints separately in Connect → Native APIs, with expiry and request limits. Source credentials remain on the server. Native response fields follow the platform account's permissions; data product field masking does not apply to this path.

Applications read data through /api/data/v1 using their own sba_ identity token. POST /query accepts a dataProduct and structured query with dataset, select, filter, groupBy, orderBy and limit. Set explainOnly to validate without reading rows. GET /schema returns approved fields; dataset is optional. POST /ask and /explain accept dataProduct, question and optional dataset and limit when AI is configured.

The SDK exposes data.query(), data.schema(), data.ask() and data.explain(). Direct queries work without an AI key. Every read checks the environment identity, active grant, approved fields, row restrictions, masking and limits. Query source credentials are never returned to applications.

An OAuth-capable MCP client connects to /api/mcp and opens browser authorization when a tool needs access. Sign in, choose a workspace, and review the requested access. Discovery metadata is available at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

A client identifies itself in one of two ways. A client that publishes an OAuth client ID metadata document, such as Claude, uses that HTTPS URL as its client_id: SpringRoll fetches it from a public address, requires it to name itself, applies the same redirect rules as registration, caches it for its Cache-Control lifetime, and shows its host on the sign-in page. Any other client registers at /api/oauth/register.

For clients without OAuth, open Agent connections from your account menu, then Manual configuration to create an agent token. Send it as Authorization: Bearer sbp_… . Copy it when it is created; the full token is shown once. Tokens act within the issuing member's permissions and cannot record human approval decisions.

A bearer credential takes precedence over a browser session. The workspace in each request must match a membership authorized by that credential.

Limits per 60-second window are 600 reads, 120 writes, 20 deployments, and 30 unauthenticated requests. Dynamic client registration allows 10 requests per hour, and one address can make SpringRoll fetch 20 client ID metadata documents per hour; cached documents do not count. Data grants have a separate queries-per-minute limit set by the data owner.

Responses provide RateLimit and RateLimit-Policy headers, plus RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and X-RateLimit-* for compatible clients. RateLimit-Reset is seconds remaining; X-RateLimit-Reset is a Unix timestamp. On a 429 response, wait for Retry-After before retrying.

Public discovery documents advertise RateLimit-Policy without consuming the request quota. Browser clients can read rate-limit headers through Access-Control-Expose-Headers.

The current REST version is v1. Additive changes can introduce fields and endpoints within a version, so clients should accept unknown response fields. Breaking changes use a new version path.

When a REST version is deprecated, responses include Deprecation, Sunset, and Link headers identifying the replacement. The notice period is at least 365 days. After sunset, the retired version returns 410 Gone.

MCP tools are versioned with the server. Call tools/list when starting a session to read the available tools and their current schemas.

An error response includes code, message and correlationId. Recoverable errors may also include details and nextActions. Use code to choose recovery behavior and check nextActions before retrying a blocked request.

Include correlationId when reporting an error. It also appears in the x-correlation-id response header. Unknown API routes return a 404 error response.

You can read /api/v1, /api/v1/capabilities, /openapi.json, /api/openapi.yaml and /api/health without signing in.

MCP initialize, tools/list, resources/list and prompts/list are also public. Calls that use workspace data require authentication. A 401 response includes a WWW-Authenticate challenge for the authorization flow.

Install the SpringRoll skill with npx skills add springroll-dev/springroll-skill --skill springroll. It helps your coding agent package the project and start a deployment. OAuth-capable MCP clients can also connect directly to /api/mcp.

Deployment requests return an id while the build continues. Poll springroll.deploy.status or GET the deployment until it reaches READY or a terminal failure. Use an Idempotency-Key when retrying a supported write: the same key and body return the original result; a changed body is rejected.