API Reference

Crewship REST API for programmatic access

Overview

The Crewship API allows you to programmatically:

• Create and manage deployments
• Trigger and monitor runs
• Access artifacts and logs
• Manage environment variables

Base URL

https://api.crewship.dev

Authentication

All API requests require authentication using an API key:

curl https://api.crewship.dev/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY"

Getting an API Key

1. Open the Crewship Console
2. Go to Settings → API Keys
3. Click Create API Key
4. Copy and store the key securely

API keys are shown only once. Store them securely and never commit them to version control.

Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	For POST/PUT	application/json
Accept	Optional	application/json (default) or text/event-stream

Request Body

POST and PUT requests accept JSON:

curl -X POST https://api.crewship.dev/v1/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment": "my-crew",
    "input": {"topic": "AI agents"}
  }'

Response Format

Success Responses

{
  "data": {
    "id": "run_abc123",
    "status": "running",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

List Responses

{
  "data": [
    { "id": "run_abc123", ... },
    { "id": "run_xyz789", ... }
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "has_more": true
  }
}

Error Responses

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: deployment",
    "details": {
      "field": "deployment"
    }
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad request (invalid parameters)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient permissions)
404	Not found
429	Rate limited
500	Server error

Rate Limits

Plan	Requests/minute	Concurrent runs
Free	60	2
Pro	300	10
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705315860

Pagination

List endpoints support pagination:

curl "https://api.crewship.dev/v1/runs?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Default	Max	Description
page	1	—	Page number
per_page	20	100	Items per page

Filtering

List endpoints support filtering:

# Filter runs by status
curl "https://api.crewship.dev/v1/runs?status=running" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by deployment
curl "https://api.crewship.dev/v1/runs?deployment=my-crew" \
  -H "Authorization: Bearer YOUR_API_KEY"

SDKs

TypeScript

Coming soon

Python

Coming soon

Go

Coming soon

API Endpoints

Deployments

Create and manage deployments

Runs

Trigger and monitor runs