API overview

Everything you can do in the dashboard, you can do over HTTP. The API is plain JSON over HTTPS at:

https://opencloudport.com/api/v1

The TypeScript SDK wraps it, and AI agents use the same actions over MCP.

KeysCopy Anchor Link

Send your key in the Authorization header:

curl https://opencloudport.com/api/v1/workspace \
  -H "Authorization: Bearer $OCP_KEY"

GET /api/v1/workspace is a handy first call: it answers with the workspace the key belongs to (id, name, slug).

There are two kinds of key:

A read-only key can only make GET requests. A key used outside its reach gets 403 key_out_of_scope. Any key can have a spending limit; once reached, changes get 402 key_spend_limit_reached and reads still work.

Every change a key makes (anything but GET) is written to its activity log, with what was done and whether it worked. Request bodies are never recorded.

RequestsCopy Anchor Link

• Send JSON with Content-Type: application/json. Deployments are the one exception: they're multipart/form-data.
• Bodies are checked strictly: an unknown field is an error, so typos don't pass silently.
• Bodies are limited to 16 KB, except where an endpoint says otherwise (SQL 128 KB, email 1 MB, sandbox files 25 MB, deployments 10 MB of code plus 50 MB of static files). Every limit is on one page: Limits.
• Ids in paths are always ids (app_…, svc_…), never names. Variable names and sandbox process names are the only names in paths.

ResponsesCopy Anchor Link

One object comes back in data:

{ "data": { "id": "app_7QxV…", "object": "app", "name": "Bakery orders", "status": "active" } }

Lists come back as:

{ "object": "list", "data": [ … ], "has_more": false }

Apps and deployments are paged: pass limit (1 to 100, default 20) and starting_after with the last id you got. Files in a bucket use cursor and next_cursor instead.

Money is in US dollars, as exact decimal strings ("12.500000"), with the same amount in millionths of a dollar alongside (balance_micros). Times are ISO 8601 in UTC.

ErrorsCopy Anchor Link

Every error has the same shape and a matching HTTP status:

{ "error": { "code": "name_taken", "message": "This app already has a service named \"DB\". Pick another name." } }

Check code in your code; message is written for people and may change. When a field is wrong, its name starts the message ("name: name is required").

IdsCopy Anchor Link

Retrying safelyCopy Anchor Link

Send an Idempotency-Key header with any POST you might retry: sending an email, deploying, creating an app or a sandbox. Use a new random value (a UUID) for each new request, and the same one when you retry it.

curl -X POST https://opencloudport.com/api/v1/apps/$APP_ID/services/$EMAIL_ID/send \
  -H "Authorization: Bearer $OCP_KEY" \
  -H "Idempotency-Key: 3f6c1a52-8d7e-4b1f-9c0a-5e2d7b9f4a11" \
  -H "Content-Type: application/json" \
  -d '{ "to": "ann@example.com", "subject": "Your order", "text": "Thanks!" }'

• A retry with the same key and the same request gets the first answer back, with the header Idempotent-Replayed: true, and nothing happens twice: one email, one deployment.
• The same key with a different request is refused with 422 idempotency_key_reused.
• A retry that arrives while the first request is still running gets 409 idempotency_in_progress; wait a moment and retry.
• Keys are remembered for 24 hours, separately for each API key. Answers that were server errors (5xx) aren't remembered, so retrying those really tries again.

These are also safe to repeat, with or without the header:

• POST /apps with the same external_id returns the app you already made.
• Deleting an app, service, sandbox or file that's already gone succeeds.
• PUT /apps/{id}/env/{NAME} sets the same value again.

Rate limitsCopy Anchor Link

Each API key has its own limit, so one busy key never slows another. Calls made by an AI agent through MCP count towards its key the same way.

Over the limit, you get 429 rate_limited with a Retry-After header in seconds. Waiting that long and retrying always works.

Money checksCopy Anchor Link

Two calls need a positive balance, and get 402 insufficient_balance without one: adding a service, and starting a sandbox. Creating an app is free. While a workspace is paused for lack of credit, sending email and using sandboxes get 402 app_paused. See How billing works.

EndpointsCopy Anchor Link