Skip to main content

​
API Overview

The Crew API provides programmatic access to all platform features. Use it to manage agents, initiate calls, configure settings, and retrieve data.

​
Base URL

https://api.usecrew.ai/v1

​
Authentication

All API requests require authentication via API key: 
curl https://api.usecrew.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"
See Authentication for details on obtaining and managing API keys.

​
Request Format

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer YOUR_API_KEY
Content-TypeFor POST/PUTapplication/json
X-Crew-VersionNoAPI version (defaults to latest)

​
Request Body

Send JSON for POST and PUT requests: 
curl -X POST https://api.usecrew.ai/v1/calls/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "agent_id": "agent_sarah"
  }'

​
Response Format

All responses are JSON: 
{
  "success": true,
  "data": {
    "id": "call_abc123",
    "status": "initiated"
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "invalid_phone_number",
    "message": "The provided phone number is not valid",
    "details": {
      "field": "to",
      "value": "not-a-number"
    }
  }
}

​
HTTP Status Codes

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

​
Core Endpoints

​
Agents

MethodEndpointDescription
GET/agentsList all agents
POST/agentsCreate agent
GET/agents/{id}Get agent details
PUT/agents/{id}Update agent
DELETE/agents/{id}Delete agent

​
Calls

MethodEndpointDescription
GET/callsList calls
POST/calls/outboundPlace outbound call
GET/calls/{id}Get call details
GET/calls/{id}/transcriptGet call transcript
GET/calls/{id}/recordingGet call recording

​
SMS

MethodEndpointDescription
GET/smsList SMS messages
POST/smsSend SMS
GET/sms/{id}Get message details

​
Knowledge Base

MethodEndpointDescription
GET/knowledge-baseList entries
POST/knowledge-baseAdd entries
PUT/knowledge-base/{id}Update entry
DELETE/knowledge-base/{id}Delete entry

​
Campaigns

MethodEndpointDescription
GET/campaignsList campaigns
POST/campaignsCreate campaign
GET/campaigns/{id}Get campaign details
POST/campaigns/{id}/startStart campaign
POST/campaigns/{id}/pausePause campaign
POST/campaigns/{id}/cancelCancel campaign

​
Webhooks

MethodEndpointDescription
GET/webhooksList webhooks
POST/webhooksCreate webhook
PUT/webhooks/{id}Update webhook
DELETE/webhooks/{id}Delete webhook

​
Pagination

List endpoints support pagination: 
curl "https://api.usecrew.ai/v1/calls?limit=50&offset=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Parameters

ParameterDefaultDescription
limit20Items per page (max 100)
offset0Skip this many items

​
Response

{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 1234,
    "limit": 50,
    "offset": 100,
    "has_more": true
  }
}

​
Filtering

Most list endpoints support filtering: 
# Filter calls by status
curl "https://api.usecrew.ai/v1/calls?status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by date range
curl "https://api.usecrew.ai/v1/calls?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by agent
curl "https://api.usecrew.ai/v1/calls?agent_id=agent_sarah" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Rate Limits

PlanRequests/Minute
Starter60
Professional300
EnterpriseCustom
Rate limit headers are included in every response: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1705312800
When rate limited, you’ll receive: 
{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Try again in 45 seconds.",
    "retry_after": 45
  }
}

​
SDKs

​
Node.js

npm install @crew/sdk

const Crew = require('@crew/sdk');

const crew = new Crew('YOUR_API_KEY');

// List agents
const agents = await crew.agents.list();

// Place a call
const call = await crew.calls.create({
  to: '+14155551234',
  agentId: 'agent_sarah'
});

​
Python

pip install crew-sdk

from crew import Crew

crew = Crew('YOUR_API_KEY')

# List agents
agents = crew.agents.list()

# Place a call
call = crew.calls.create(
    to='+14155551234',
    agent_id='agent_sarah'
)

​
Idempotency

For operations that shouldn’t be duplicated, use idempotency keys: 
curl -X POST https://api.usecrew.ai/v1/calls/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{
    "to": "+14155551234",
    "agent_id": "agent_sarah"
  }'
Repeat requests with the same key return the original response.

​
Versioning

The API is versioned. Specify a version for stability: 
curl https://api.usecrew.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Crew-Version: 2024-01-15"
Without a version header, you get the latest stable version.

​
Webhooks

Receive real-time updates via webhooks. See Webhooks for details.

​
Testing

​
Sandbox Mode

Use sandbox mode for testing without real calls: 
curl -X POST https://api.usecrew.ai/v1/calls/outbound \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Crew-Sandbox: true" \
  -d '{
    "to": "+14155551234",
    "agent_id": "agent_sarah"
  }'
Sandbox calls return realistic responses but don’t place actual calls.

​
Test Phone Numbers

Use these numbers for testing:
NumberBehavior
+15551234567Always answers
+15551234568Always busy
+15551234569No answer
+15551234560Voicemail

​
Next Steps