# 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?**

- **Building a product on Maritime?** Use the [SDK](/content/docs/build/index.html) (TypeScript/Python); see the SDK reference for supported helpers.
- **Driving your own agents over HTTP?** This page: Bearer auth with an `mk_` key.

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

```json
{
  "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
```

```json
{
  "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
```

```json
{
  "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...

```json
{
  "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.

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

## Swarms

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

- `POST /api/swarms`: start a run. 201...