REST API

The reference below is rendered by Scalar from the Cariosan OpenAPI spec. The viewer resolves the spec URL in this order:

1. NEXT_PUBLIC_CARIOSAN_OPENAPI_URL set at docs-build time — point this at a hosted Cariosan server's /openapi.json for the always-current spec.
2. /openapi.json served as a static snapshot from this docs site (apps/docs/public/openapi.json). Regenerate the snapshot by booting any Cariosan server, fetching /openapi.json, and committing the result into public/.

Authentication

• Server-side endpoints (/v1/users, /v1/channels, /v1/webhooks, etc.) take your workspace API credentials as Authorization: Bearer <api_key>:<api_secret>.
• Client-side endpoints (/v1/me/channels, /v1/channels/:id/messages, /v1/attachments/presign) take a user JWT as Authorization: Bearer <jwt>. Issue these from your backend with the Go SDK's IssueUserToken.

Private attachment downloads

public_url returned by upload presigning and attachment_url on a message are stable references. They no longer authorize anonymous reads. Request a fresh download grant using the message ID and channel external ID:

curl -X POST "$CARIOSAN_URL/v1/channels/team_1/messages/$MESSAGE_ID/attachment" \
  -H "Authorization: Bearer $USER_TOKEN"

Response: { "url": "https://storage.example/...signed...", "expires_at": "..." }. Only current members of the matching workspace and channel can request a grant. Deleted messages are unavailable. Grants expire after five minutes and remain usable until expiry even if membership is later revoked. Do not persist signed URLs or include them in analytics. Refresh a grant after expiry.

const grant = await client.channel("team_1").getAttachmentDownload(message.id);
// Use grant.url as the temporary image src or download href.
// Retain message.attachment_url as the stable reference, never grant.url.

Upload references are restricted to the authenticated uploader's workspace/user prefix. Reusing another user's raw object reference as a new attachment is rejected. Existing messages retain their references and can be resolved through the authorized endpoint while the configured bucket and URL base remain unchanged.