Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.bigspin.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every request to the Bigspin public API must include an API key. API keys authenticate your requests and tie them to your workspace, which determines which projects and transcripts you can access. New keys use the sk-bigspin-api03- prefix so you can identify them at a glance.
Legacy keys with the sk-prism-api03- prefix (issued before the Bigspin rename) are still accepted — you do not need to rotate them. New keys you create today will use sk-bigspin-api03-.

​
Getting an API key

1

Open API Keys settings

In the Bigspin dashboard, navigate to Settings → API Keys.
2

Create a new key

Click Create API Key, give it a descriptive name (for example, production-prompt-fetcher), and optionally add a description. Then click Create API Key.
3

Copy the key immediately

Bigspin shows the full key only once. Copy it to a secure location — a secrets manager, environment variable, or vault — before closing the dialog.
Bigspin cannot show you the full key again after you close the creation dialog. If you lose it, revoke the key and create a new one.

​
Including the key in requests

Pass your API key in the Authorization header using the Bearer scheme: 
Authorization: Bearer YOUR_API_KEY
Here is a complete example using curl: 
curl -X GET "https://app.bigspin.ai/public/api/v1/projects" \
  -H "Authorization: Bearer sk-bigspin-api03-your-api-key" \
  -H "Content-Type: application/json"

​
Permissions

API keys can be scoped to specific permissions when you create them. The current permissions are:
PermissionGrants access to
projects-readList and read projects, list and read transcripts
projects-writeCreate projects, upload transcripts
Leaving an API key with no permission restrictions grants full access. Scope keys to least privilege when integrating with production systems.
Legacy keys may carry a halfpipe-transcripts-write permission instead of projects-write — both are accepted for the create-project and upload-transcript endpoints, so existing integrations continue to work without changes.
Response shape change for legacy /halfpipe/* routes (2026-05). POST /public/api/v1/halfpipe/sessions and POST /public/api/v1/halfpipe/transcripts now return the same response shape as the new /projects/* routes: snake_case fields (created_at, model_name, turn_count), no success: true flag, and no workspaceId field. If your integration parses response.success or response.data.workspaceId from these endpoints, update it to read from the new shape. The path and request body are unchanged.
JWT tokens (which start with ey) are not supported on most public API endpoints. Always use an API key with the sk-bigspin-api03- prefix.

​
Authentication error responses

When the API cannot authenticate your request, it returns a JSON error body alongside an HTTP error status. Missing API key — 401 Unauthorized 
{
  "error": {
    "message": "API key required for authentication",
    "type": "authentication_error",
    "code": 401
  }
}
Invalid API key — 401 Unauthorized 
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": 401
  }
}
Insufficient permissions — 403 Forbidden 
{
  "error": {
    "message": "API key does not have permission for this endpoint",
    "type": "authorization_error",
    "code": 403
  }
}
A 403 response means your key is valid but does not have access to the specific project or transcript you requested. Check that the key was created in the same workspace that owns the resource, and that it carries the right permission (projects-read for read endpoints, projects-write for create/upload endpoints).

​
Managing API keys

From Settings → API Keys you can:
  • Revoke a key to suspend access without permanently deleting it. Revoked keys can be reactivated later.
  • Delete permanently a key to remove it from the system entirely. This cannot be undone.
  • View last-used timestamps to audit which keys are still active.

​
Security best practices

  • Store API keys in environment variables or a secrets manager. Never hard-code them in source files or commit them to version control.
  • Create one key per environment (development, staging, production) so you can rotate or revoke them independently.
  • Revoke any key immediately if you suspect it has been exposed.
  • Rotate keys periodically as part of routine security hygiene.