Command Palette

Search conversations, projects, playbooks, and more

API Overview

Base URL, authentication, pagination, rate limits, and error handling.

The crewkit API is a JSON REST API. All endpoints are under /api/v1/.

Base URL

EnvironmentURL
Productionhttps://api.crewkit.io/api/v1

For local development and testing, set the CREWKIT_API_URL environment variable.

Authentication

All API requests (except auth endpoints and health checks) require a Bearer token:

Authorization: Bearer <access_token>

Access tokens expire after 4 hours. Use the refresh token to get a new one. See Authentication for the full flow.

Request format

Send JSON bodies with Content-Type: application/json:

curl -X POST https://api.crewkit.io/api/v1/auth/device \
  -H "Content-Type: application/json"

Response format

Successful responses return JSON with a data key (or resource-specific key):

Workspaces

Multi-repo projects for teams with split codebases.

Authentication

Device flow, passkeys, magic links, and token management.

On this page

Base URLAuthenticationRequest formatResponse formatResource IDsPaginationRate limitsError formatHTTP status codesOrganization-scoped routesNext steps
{
  "data": { ... },
  "meta": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 123
  }
}

Resource IDs

All API responses use UUID v4 for resource identifiers. These are exposed via the id field in responses and used in URL paths:

GET /api/v1/:org_id/sessions/432e16a3-0bf4-4117-8ee0-9a3b21ebe07b

Pagination

List endpoints support cursor-based pagination:

ParameterDescriptionDefault
pagePage number1
per_pageItems per page25

Pagination metadata is included in the meta key of the response.

Rate limits

ScopeLimit
Per organization1,000 requests/hour
Per IP address100 requests/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1697040000

Error format

Errors return a JSON body with an error key:

{
  "error": "Validation failed: Name can't be blank",
  "details": {
    "name": ["can't be blank"]
  }
}

HTTP status codes

CodeMeaning
200Success
201Created
400Bad request — missing or invalid parameters
401Unauthorized — missing or invalid token
403Forbidden — insufficient permissions
404Not found
422Unprocessable entity — validation error
429Too many requests — rate limited
500Internal server error

Organization-scoped routes

Most endpoints are scoped to an organization. The organization ID appears in the URL path:

GET /api/v1/:org_id/sessions
GET /api/v1/:org_id/projects

Replace :org_id with your organization's external ID (UUID).

Next steps

  • Authentication
  • Sessions API