api

REST API

The Maritime REST API is the HTTP interface behind the CLI, the SDKs and the dashboard: one Bearer key creates and drives agents, sandboxes, swarms and computers programmatically.

Which API do I want?

Base URL: https://api.maritime.sh

Check it's alive (no auth needed):

GET /health

curl https://api.maritime.sh/health
# response includes {"status":"ok", ...}

Authentication

Mint a personal API key with maritime keys create and send it as a Bearer token, the same token the CLI itself uses. Every authenticated endpoint on this page accepts it.

curl -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  https://api.maritime.sh/api/agents

Account limits

Your plan, how many machines you have and how many are awake against its caps, and the size ceilings for one agent. Any key works. A cap that does not apply is null.

GET/api/v1/account/limits

{
  "plan": "growth",
  "billingModel": "usage",
  "includedMachines": null,
  "machines": 3,
  "maxAwakeMachines": 10,
  "awakeMachines": 1,
  "minMemMb": 512,
  "maxMemMb": 8192,
  "maxDiskGb": 100,
  "agentCreatesPerMinute": 30,
  "agentDuplicatesPerMinute": 10
}

Templates

List available agent templates. Public, no auth.

GET /api/templates

Agents

GET /api/agents

POST /api/agents

Create returns 201 and starts deploying immediately. Always pass templateId (see GET /api/templates).

{
  "name": "my-agent",
  "templateId": "openclaw"
}

An optional network object sets what the agent may reach on the internet...

GET /api/agents/{agent_id}

DELETE /api/agents/{agent_id}

Chat with an agent

Sends a message through the same delivery path Telegram and webhooks use. Sleeping serverless agents wake automatically; the call waits for the reply.

POST /api/agents/{agent_id}/chat

curl -X POST https://api.maritime.sh/api/agents/AGENT_ID/chat \
  -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "summarize today"}'

# → { "response": "..." }

Lifecycle

Rarely needed (agents sleep and wake on their own), but available for ops:

POST /api/agents/{agent_id}/start

POST /api/agents/{agent_id}/stop

POST /api/agents/{agent_id}/sleep

POST /api/agents/{agent_id}/restart

Logs

GET /api/agents/{agent_id}/logs

curl -H "Authorization: Bearer mk_xxxxxxxxxxxx" \
  "https://api.maritime.sh/api/agents/AGENT_ID/logs?limit=100&level=error"

Files

Move files in and out of a running agent's sandbox and manage its disk.

GET /api/agents/{agent_id}/files/list?path=/data

GET /api/agents/{agent_id}/files/download?path=/data/report.pdf

POST /api/agents/{agent_id}/files/upload

{
  "path": "/data/notes.md",
  "content": "This is a note."
}

PUT /api/agents/{agent_id}/files/write

POST /api/agents/{agent_id}/files/mkdir

POST /api/agents/{agent_id}/files/move

Run a command

Run a non-interactive command in your agent.

POST /api/agents/{agent_id}/exec

{
  "command": ["printf", "hello\n"],
  "timeout": 30
}

Deleted agent history

Deleting an agent keeps a read-only copy of its recent history for 7 days.

curl -H "Authorization: Bearer $MARITIME_API_KEY" \
  https://api.maritime.sh/api/v1/deleted-agents/AGENT_ID

Feedback

Tell Maritime when a doc is wrong, an example does not run, or a call fails...

curl -X POST https://api.maritime.sh/api/v1/feedback \
  -H "Authorization: Bearer $MARITIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "api", "subject": "POST /api/agents/{agent_id}/chat" }'

End users

An end user is one of your users, keyed by the id you already hold for them...

{
  "externalUserId": "user_42",
  "name": "My User"
}

Usage

What your agents cost over a range...

GET /api/v1/usage

Sandboxes

Start a sandbox that ends when it goes idle, in one call.

{
  "name": "job-42",
  "idleMinutes": 5,
  "timeLimitMinutes": 60
}

Swarms

A swarm runs one shell command on many sandboxes and collects each result.