API Overview

CraftDesk's REST API lets you integrate with your tools, automate workflows, and build custom applications on top of CraftDesk data.

Base URL

The CraftDesk API is available at:

https://api.craftdesk.app/v1/

All requests must go to the secure HTTPS endpoint. HTTP requests are not supported.

Authentication

All API requests require authentication via Bearer tokens. Include your API key in the Authorization header:

curl -H "Authorization: Bearer your_api_key" https://api.craftdesk.app/v1/projects

Generate API keys in Settings → Integrations → API Keys. Each key is tied to the creator's workspace and inherits their permissions.

Response Format

All API responses are JSON with snake_case keys. Responses include:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Website Redesign",
      "description": "Modernize our web presence",
      "created_at": "2025-03-23T14:35:21Z",
      "updated_at": "2025-03-23T14:35:21Z"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total": 50,
      "per_page": 20
    }
  }
}

Error Responses

Errors include a status code and descriptive message:

{
  "message": "Unauthorized",
  "code": 401,
  "errors": {
    "api_key": ["Invalid or expired API key"]
  }
}

Common error codes:

Rate Limiting

Rate limits depend on your plan:

Your rate limit resets on the first day of each month. When you exceed your monthly limit, the API returns 429 (Too Many Requests) until the next billing cycle.

Headers included in responses show your quota status:

X-RateLimit-Limit: 50000
X-RateLimit-Remaining: 48999
X-RateLimit-Reset: 1749739200

Pagination

List endpoints return paginated results. Control pagination with query parameters:

GET /v1/projects?page=2&per_page=50

Available parameters:

• page — Which page to retrieve (default: 1)
• per_page — Results per page (default: 20, max: 100)

The response includes pagination metadata:

{
  "meta": {
    "pagination": {
      "current_page": 2,
      "total": 150,
      "per_page": 50,
      "last_page": 3
    }
  }
}

Common Headers

Include these headers in all API requests:

Content-Type: application/json
Authorization: Bearer your_api_key
X-Requested-With: XMLHttpRequest

Supported Methods

CraftDesk API uses standard HTTP methods:

• GET — Retrieve resources
• POST — Create resources
• PATCH — Update resources
• DELETE — Remove resources

Example Request

Here's a complete example retrieving all projects:

curl -X GET \
  "https://api.craftdesk.app/v1/projects?per_page=50" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Website Redesign",
      "slug": "website-redesign",
      "created_at": "2025-03-23T10:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total": 5,
      "per_page": 50
    }
  }
}

Rate Limit Strategy

To avoid hitting rate limits:

• Batch operations — Retrieve multiple resources in one call when possible
• Cache results — Store API responses locally and refresh periodically
• Use webhooks — Subscribe to events instead of polling repeatedly
• Optimize queries — Use filtering parameters to fetch only needed data

What's Next

• Authentication — Manage API keys and security
• Webhooks — Build real-time integrations
• API Endpoints Reference — Detailed endpoint documentation (see craftdesk.app/api/docs)