API Reference

RESTful API for managing agents programmatically.

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

Check it's alive (no auth needed):

curl https://api.maritime.sh/health
# → {"status":"ok","runtime":"docker"}

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

Building a platform on Maritime (per-customer agents, scoped keys, wallet)? Use the Provisioning API, which authenticates with X-API-Key and enforces per-key scopes.

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).

POST /api/agents (body)

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

GET /api/agents/{agent_id}

DELETE /api/agents/{agent_id}

Delete returns 204 and removes the container and its data volume.

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": "..." }
# Optional: pass "conversation_id" to continue a thread.

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?lines=100&level=error"

Deploy

Redeploy an agent from its template, a GitHub repo, or a Docker image:

POST /api/deploy

POST /api/deploy (body)

{
  "agentId": "AGENT_ID",
  "source": "github",
  "repoUrl": "https://github.com/you/app",
  "branch": "main"
}

Webhooks

Every agent has a public invoke URL. No auth header is needed; treat the URL itself as the secret. A POST wakes the agent (if asleep) and delivers the payload as a message:

POST /api/webhooks/{agent_id}

Looking for more?

Environment variables, custom build files, and wallet operations live in the Provisioning API; everything else is scriptable via the CLI. Run maritime guide --json for the full machine-readable surface. Dashboard-internal endpoints are intentionally undocumented and may change without notice.