REST API

Credits and limits

Understand charging, rate limits, waits, and timeouts.

Each module declares one fixed positive `credits_per_request` value. Every capability in that module is published and charged at that fixed cost.

## When credits are charged

Credits are charged once when a logical job completes successfully.

The following do not add another capability charge:

- a pending response;
- polling a job;
- internal worker retries;
- a failed job;
- an idempotent replay of the same logical request.

Credit reservations prevent concurrent requests from overspending the same remaining balance. A zero balance blocks new execution.

## Find the cost

The public platform page displays the credit cost next to every capability. The value comes from the registered module snapshot, not from page-specific copy.

## Wait limits

REST accepts `Prefer: wait=N` with a maximum of 300 seconds. A shorter wait reduces open connection time; a longer wait can avoid polling for capabilities that normally finish quickly.

MCP waits for up to 55 seconds by default. Work that remains active returns a pending job ID for later retrieval.

## Capability timeouts

Each capability manifest declares `timeout_ms`. That worker deadline is distinct from the HTTP wait window. Ending an HTTP wait does not mean the worker timed out, and increasing `Prefer: wait` cannot extend the capability's registered execution timeout.

## Rate limits

Rate limits apply to authenticated API and MCP traffic. A limited request returns HTTP `429` with both `Retry-After` and `retry_after_ms`. Respect the advertised delay rather than using a fixed aggressive retry interval.

Each module declares one fixed positive credits_per_request value. Every capability in that module is published and charged at that fixed cost.

When credits are charged

Credits are charged once when a logical job completes successfully.

The following do not add another capability charge:

a pending response;
polling a job;
internal worker retries;
a failed job;
an idempotent replay of the same logical request.

Credit reservations prevent concurrent requests from overspending the same remaining balance. A zero balance blocks new execution.

Find the cost

The public platform page displays the credit cost next to every capability. The value comes from the registered module snapshot, not from page-specific copy.

Wait limits

REST accepts Prefer: wait=N with a maximum of 300 seconds. A shorter wait reduces open connection time; a longer wait can avoid polling for capabilities that normally finish quickly.

MCP waits for up to 55 seconds by default. Work that remains active returns a pending job ID for later retrieval.

Capability timeouts

Each capability manifest declares timeout_ms. That worker deadline is distinct from the HTTP wait window. Ending an HTTP wait does not mean the worker timed out, and increasing Prefer: wait cannot extend the capability's registered execution timeout.

Rate limits

Rate limits apply to authenticated API and MCP traffic. A limited request returns HTTP 429 with both Retry-After and retry_after_ms. Respect the advertised delay rather than using a fixed aggressive retry interval.