API Overview
Authentication
All API calls require authenticating with your API key. You can create and expire tokens in the dashboard.
The HTTP API expects the API key to be formatted as a standard Bearer token and passed in the Authorization header:
Authorization: Bearer <API_KEY>
Encoding
The API uses JSON encoding for both request and response payloads.
Compression
The API supports standard HTTP compression headers.
However, for most workloads, disabling compression offers the best performance. turbopuffer clients are typically CPU constrained, not network bandwidth constrained.
The official client libraries disable request and response compression by default.
Error responses
If an error occurs for your request, all endpoints will return a JSON payload in the format:
{
"status": "error",
"error": "an error message"
}
You may encounter an HTTP 429 if you query or write too quickly. See limits for more information.
Asynchronous requests
Some long-running operations can run asynchronously rather than holding the connection open until they finish. The official client libraries handle this automatically and transparently — just make sure to configure the request timeout long enough for the operation to complete. The rest of this section is only relevant if you call the HTTP API directly.
Currently supported operations:
Send the Prefer: respond-async header to allow the server to start the operation in the background.
The server returns 202 Accepted with a Location header pointing to the operation.
Poll that location to check on progress: The response is {"status": "running"} until the operation finishes, then carries the result.
Note that the Prefer: respond-async header is just a hint.
The server may return a sync response, for efficiency or load reasons.
Examples
import turbopuffer
tpuf = turbopuffer.Turbopuffer(region='gcp-us-central1')
ns = tpuf.namespace(f'asyncreq-dst-py')
# Allow up to 30 minutes for the call to complete.
ns.copy_from(
source_namespace=f'asyncreq-src-py',
timeout=30 * 60,
)Specification
The API has a public OpenAPI specification available at:
