REST API

The REST API is the same one the Fishcamp app uses. Everything is JSON over HTTPS.

https://api.fishcamp.space/api/v1

AuthenticationCopy Anchor Link

Every request carries a bearer token:

Authorization: Bearer cwk_YOUR_KEY

• Scripts, bots and AI agents use an API key (cwk_…). Every GET needs the read scope; creating or changing things needs write. A key sees what the admin who created it sees, and an AI agent's key only reaches the agent's channels.
• The Fishcamp app calls the same endpoints with the signed-in person's short-lived session token.
• Admin actions need a person. Endpoints marked Admins refuse API keys with 403 forbidden, and so do those marked People. A key never acts as an admin, even when an admin created it.
• Some routes need no key or session. Incoming webhooks carry their secret in the URL. Guests use the /meet/:code routes without an account (sending audio takes the guest token they get when they join), and the invite link preview, GET /invite-links/:code, is public.

A missing, invalid or expired token gets 401 unauthorized.

The workspace headerCopy Anchor Link

Endpoints that work inside a workspace (channels, messages, members, audio rooms, invite and meeting links, webhooks, API keys, AI agents, transcripts, integrations) need the workspace's ID:

X-Workspace-Id: 9b2f6c1d-3e4a-4f5b-8c7d-1a2b3c4d5e6f

GET /workspaces lists the workspaces of the signed-in person with their IDs; for an API key, the MCP tool whoami returns its workspace. Without the header, or for a workspace you're not a member of, the answer is 403 forbidden. A key only works in its own workspace: with a key the header is optional, and another workspace's ID gets 403.

A first requestCopy Anchor Link

curl "https://api.fishcamp.space/api/v1/channels" \
  -H "Authorization: Bearer cwk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

[
  {
    "id": "0b6f3c55-2a51-4e0a-a3d6-6a3f1f2e9d10",
    "workspaceId": "9b2f6c1d-3e4a-4f5b-8c7d-1a2b3c4d5e6f",
    "kind": "STANDARD",
    "visibility": "PUBLIC",
    "name": "general",
    "topic": "Team conversations",
    "voiceEnabled": true,
    "cameraEnabled": true,
    "screenShareEnabled": true,
    "transcriptionEnabled": false,
    "createdAt": "2026-11-02T13:05:11.000Z",
    "lastMessageAt": "2026-11-05T14:32:08.000Z",
    "directPeer": null,
    "isMember": true,
    "unread": false
  }
]

ConventionsCopy Anchor Link

• IDs are UUIDs. Dates are ISO 8601 in UTC.
• Creating returns 201 Created with the new object. Deleting and actions without a result return 204 No Content.
• Visibility: a private channel you're not in, or a channel, message, member or invite ID from another workspace, answers 404 not_found, never 403, so the API doesn't reveal that it exists. (A whole workspace you're not in, named in X-Workspace-Id, answers 403.)
• Request IDs: every error carries a requestId. Send your own in an X-Request-Id header (6 to 64 letters, digits, _ or -) to match logs on both sides.
• Body size: up to 512 KB per request. Audio sent for transcription goes in chunks of up to 1 MB.
• Email language: POST /auth/email-code (the sign-in code) and POST /workspace/invites take an optional locale, en (the default), pt or es, and send the email in that language. Any other value gets 422. New in November 2026

ErrorsCopy Anchor Link

Every error has the same shape:

{
  "error": {
    "code": "validation_error",
    "message": "Some fields are invalid",
    "details": { "errors": [{ "path": "content", "message": "Messages must be 1 to 4000 characters" }] },
    "requestId": "req_5f0c2a9b1e7d4c3a"
  }
}

message is written for people and can be shown as is. details only appears when there's something useful in it, like the list of invalid fields (up to 20).

Rate limitsCopy Anchor Link

Requests are counted per client address, per endpoint and per minute. Over the limit, the answer is 429 rate_limited.

PaginationCopy Anchor Link

Lists that can grow without end, like messages, are paginated with a cursor. Each page has a nextCursor; pass it as cursor to get the next (older) page, until nextCursor is null. See Message endpoints.

EndpointsCopy Anchor Link

GET /health needs no token and answers { "status": "ok", "version": "…" } while the API is up.