Developer surfaces

Two ways to drive Cold OS.

REST for humans and scripts. MCP for AI agents. Same operator surface, two protocols.

For humans

Public REST API

Versioned HTTP endpoints with OpenAPI 3.1, Bearer-key auth, and an in-browser Try-It runner.

· 46 endpoints across 17 resources
· OpenAPI 3.1 + Try-It runners
· Bearer keys with scoped grants
· 1k/min workspace · 120/min per key

Browse the API

Admin only

MCP server

AI agents (Claude Desktop, Cursor, n8n) drive Cold OS through the Model Context Protocol.

· 17 tools (read + write, draft-only sends)
· 4 prompts as slash commands
· 4 resources for passive context
· RLS-bound per operator key

Browse MCP

Bearer keys

Authorization: Bearer … on every request.

Scoped grants

Pick the smallest resource:action set per key.

Rate limits

1k/min workspace, 120/min per key. 429 on overflow.

Quick start

Your first request in 30 seconds.

Generate an API key from Settings → API keys, then send a request to any /v1/* endpoint with a Bearer header. Base URL: coldos.justgotwyrd.com/api.

Authenticate Browse the API

curl https://coldos.justgotwyrd.com/api/v1/contacts \
  -H "Authorization: Bearer $COLD_OS_API_KEY"

Resources

Core resources

Contacts

People records — stages, tags, custom fields.

Flows

Multi-step workflows — email, wait, branch, call, task.

Sent emails

Send and read mail through the operator's Gmail.

Tasks

Operator follow-ups, manual or flow-spawned.

Calls

Outbound + inbound call logs (Twilio bridge).

Meetings

Cold OS-originated Google Calendar events.

Foundations

Get the basics right.

Authentication

Bearer keys, scopes, rotation.

Webhooks

Push events to your endpoint with HMAC verify.

Errors

HTTP codes + canonical error shape.

Doctrine

What you can rely on.

Every external write goes through the outbox. We never block your request on a downstream provider.
API keys are workspace-scoped. Rotate freely — old keys are reject-listed instantly.
Resource IDs use UUIDv4 for relational rows and ULIDs for flow-engine rows. Both are 128-bit and lexicographically sortable.
All timestamps are ISO 8601 with the Asia/Kolkata offset stamped explicitly. There is no implicit timezone.

Was this page helpful?

Your vote stays in this browser. We'll use it to prioritise rewrites.