Docs / YouSpot API versioning, deprecation and rate limits

YouSpot API versioning, deprecation and rate limits

How the YouSpot API is versioned, what notice you get before anything is removed, the RateLimit headers every limited endpoint answers with, and how Idempotency-Key makes a retry safe.

An agent should not have to guess whether the surface it integrated against will still be there next month. This page is the contract.

Versioning

The API is versioned in the URL path. /mcp/v1 is the current product MCP server and /v1 is the agent index. A version never changes meaning underneath you: a breaking change gets a new path, not a new shape at the old one.

• Adding an endpoint, a response field, an optional parameter or a new MCP tool is not breaking, and happens without notice.
• Removing or renaming a field, tightening a type, or removing an endpoint or tool is breaking, and only ever happens at a new version path.
• The OpenAPI document at /openapi.json always describes what is live right now.

Deprecation and sunset

A path being retired answers with Deprecation: true (RFC 9745) and a Link header with rel="successor-version" naming what replaces it. Once a removal date is set, the same responses carry Sunset (RFC 8594) as an HTTP-date.

The commitment: at least 180 days between the first Sunset header and the path being removed, and a deprecated path keeps working unchanged for that whole window. Watch for the header rather than polling this page.

curl -sD - -o /dev/null https://youspot.com/mcp
# Deprecation: true
# Link: <https://youspot.com/mcp/v1>; rel="successor-version"

Rate limits

Every limited endpoint answers with the RFC 9331 headers, so you can pace against the real budget instead of backing off blindly. The dashed triple is sent alongside for clients that parse it.

The sandbox MCP server allows 60 calls a minute per address. A 429 is a JSON-RPC error with code -32003 and a Retry-After header.

Idempotency

A dropped connection leaves an agent unable to tell a lost response from a refused request. Send Idempotency-Key on a write and the retry is safe: the first answer is replayed rather than the write repeating.

• The key is any unique string up to 255 characters. A UUID is the usual choice.
• A key is scoped to the credential that sent it, so it replays only your own answer. It does not need to be unguessable.
• A recorded answer is replayed for 24 hours, with Idempotency-Replayed: true.
• The same key with a different request body is a 422, because that is a client bug rather than a retry.
• Honoured on POST /oauth/register, POST /mcp/v1 and POST /mcp/sandbox, and declared on those operations in /openapi.json.

curl -X POST https://youspot.com/oauth/register \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"redirect_uris":["https://example.com/callback"],"client_name":"My agent"}'

Work that outlives one request

A tool that cannot finish inside one call enqueues instead and answers with task_id. Poll GET /api/jobs/<task_id> until terminal is true; while it is still going the response carries Retry-After with the interval to use. result is filled once state is succeeded.

curl https://youspot.com/api/jobs/8412 \
  -H "Authorization: Bearer $YOUSPOT_TOKEN"
# {"job_id":8412,"kind":"file_import","state":"running","terminal":false,...}