API Overview

start.chat REST API documentation

The start.chat API lets you programmatically interact with servers, channels, messages, and more.

Base URL

https://start.chat/api/v1

Authentication

All API requests require authentication via an API key:

curl -H "Authorization: Bearer sk_live_xxx" https://start.chat/api/v1/...

Get your API key from Server Settings → API Keys in the app.

API keys are scoped to a single server and inherit the permissions of the role they’re assigned to. Keys use the format sk_live_*.

Key permissions

Permissions are enforced by Zero’s row-level permission model. Your API key inherits the role flags of its assigned role, and Zero checks these against each resource’s write rules.

Response format

All responses are JSON with this structure:

// Success
{
  "ok": true,
  "data": { ... }
}

// Error
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Resources

Standard CRUD Operations

Most resources support these standard operations with consistent request/response formats:

Create (POST)

curl -X POST "https://start.chat/api/v1/{resources}" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "id": "generated_id", ...fields }'

Update (PATCH)

curl -X PATCH "https://start.chat/api/v1/{resources}/:id" \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "id": "resource_id", ...fieldsToUpdate }'

Delete (DELETE)

curl -X DELETE "https://start.chat/api/v1/{resources}/:id" \
  -H "Authorization: Bearer sk_live_xxx"

All CRUD operations return:

{
  "ok": true,
  "data": {
    "id": "resource_abc123",
    "createdAt": 1709251200000
  }
}

Rate limits

Requests are rate-limited per user per resource using a sliding window. Rate-limited responses include headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 5
X-RateLimit-Reset: 1704067200
Retry-After: 45

Error codes

{
  "ok": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 45 seconds."
  }
}

Queries

Read endpoints use GET with REST paths:

curl "https://start.chat/api/v1/servers/{serverId}" \
  -H "Authorization: Bearer sk_live_xxx"

Available queries:

See the SDK queries reference for typed parameters.

Permissions by Resource

Each resource defines its own write permission rules, enforced by Zero at the row level: