API Overview

The Tapioca API provides programmatic access to all features available in the web interface. Whether you’re building integrations, automating workflows, or creating custom tools, the API gives you full control.

Base URL

All API requests should be made to:

https://your-instance.tapioca.dev/api/v1

For self-hosted installations, replace with your domain:

https://tapioca.your-company.com/api/v1

API Versioning

The API is versioned via the URL path. The current version is v1. We maintain backward compatibility within major versions and provide deprecation notices before making breaking changes.

Request Format

• All requests must use HTTPS
• Request bodies should be JSON with Content-Type: application/json
• All timestamps use ISO 8601 format in UTC

Example Request

curl -X POST https://api.tapioca.dev/api/v1/tasks 
  -H "Authorization: Bearer YOUR_API_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "Implement new feature",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "priority": "high"
  }'

Response Format

All responses are JSON. Successful responses include the requested data:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Implement new feature",
  "status": "todo",
  "priority": "high",
  "createdAt": "2024-01-15T10:30:00Z"
}

List endpoints return paginated responses:

{
  "items": [...],
  "total": 42,
  "offset": 0,
  "limit": 20
}

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "validation_error",
  "message": "Title is required",
  "details": {
    "field": "title",
    "code": "required"
  }
}

Common Status Codes

Rate Limiting

API requests are rate limited to ensure fair usage:

• Standard: 1000 requests per minute
• Burst: Up to 100 requests per second

Rate limit headers are included in every response:

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

Pagination

List endpoints support pagination via query parameters:

Example:

GET /api/v1/tasks?offset=20&limit=10

Filtering & Sorting

Most list endpoints support filtering and sorting:

# Filter by status
GET /api/v1/tasks?status=in_progress

# Sort by creation date (descending)
GET /api/v1/tasks?sort=-createdAt

# Combine filters
GET /api/v1/tasks?status=todo&priority=high&sort=dueDate

SDKs & Libraries

Official SDKs are coming soon. In the meantime, you can use any HTTP client:

• curl - Command line
• fetch/axios - JavaScript/TypeScript
• requests - Python
• net/http - Go

OpenAPI Specification

The full API specification is available in OpenAPI 3.0 format:

• Download OpenAPI Spec
• Interactive API Explorer (coming soon)

Next Steps