API Overview

Our REST API allows you to programmatically access and manipulate data in your workspace. This guide covers the fundamentals you need to get started.

Base URL

All API requests should be made to:

https://api.example.com/v1

Authentication

All API requests require authentication using an API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v1/projects

Getting Your API Key

1. Go to Settings > API
2. Click Generate New Key
3. Copy and store your key securely
4. Keys are shown only once!

Key Permissions

Rate Limits

API requests are rate limited by plan:

Rate Limit Headers

Every response includes rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1640000000

Request Format

Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

All POST/PUT requests should use JSON:

{
  "name": "My Project",
  "description": "A new project"
}

Response Format

Success Response

{
  "success": true,
  "data": {
    "id": "proj_123abc",
    "name": "My Project",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": {
      "field": "name"
    }
  }
}

HTTP Status Codes

Pagination

List endpoints support pagination:

GET /v1/projects?limit=20&offset=0

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Quick Examples

List All Projects

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v1/projects

Create a Task

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Task", "project_id": "proj_123"}' \
  https://api.example.com/v1/tasks

Update a Task

curl -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}' \
  https://api.example.com/v1/tasks/task_456

SDKs & Libraries

Official SDKs are available for:

• JavaScript/Node.js: npm install @example/sdk
• Python: pip install example-sdk
• Ruby: gem install example-sdk
• Go: go get github.com/example/sdk

Next Steps

• Authentication Deep Dive
• Webhooks
• Full API Reference