API Overview

The Doto API is a RESTful HTTP API. All requests and responses use JSON.

Base URL

http://localhost:3000

Authentication

All API endpoints that manage Doto resources require an API key.

The unauthenticated endpoints are:

• GET /health
• GET /api/v1/auth/google
• GET /api/v1/auth/google/callback

Pass it in the Authorization header:

Authorization: Bearer doto_xxxxxxxx...

Requests without a valid key return 401:

{ "error": "Unauthorized", "code": "AUTH_REQUIRED" }

Response format

Success

{
  "data": { ... }
}

Paginated list

{
  "data": [ ... ],
  "meta": {
    "cursor": "eyJpZCI6Ii4uLiJ9",
    "hasMore": true
  }
}

Pass cursor as a query parameter to fetch the next page. Use limit to control page size (default: 20, max: 100).

Error

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

Error codes

Code	HTTP	Description
AUTH_REQUIRED	401	Missing or invalid API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource does not exist
VALIDATION_ERROR	400	Invalid request body or parameters
OAUTH_STATE_MISMATCH	400	OAuth callback state is missing or invalid
INVALID_TRANSITION	400	Task status transition not allowed
MAX_KEYS_REACHED	400	User already has 10 active API keys
CONFLICT	409	General uniqueness conflict
INTERNAL_ERROR	500	Unexpected server error

Endpoints

• Users
• Auth
• Teams
• Tasks
• Inbox