SDK Reference

Complete reference for both Maritime SDKs. New here? Start with the Build on Maritime guide.

Language	Package	Install
TypeScript / JS	maritime-sdk	npm install maritime-sdk
Python	maritime	pip install maritime

Both are zero-dependency. Source: github.com/maritime-sh/maritime-sdk.

Client

The API key defaults to MARITIME_API_KEY; the base URL to MARITIME_API_URL or api.maritime.sh.

import { Maritime } from 'maritime-sdk'

const maritime = new Maritime({
  apiKey: 'mk_...',                     // or MARITIME_API_KEY
  baseUrl: 'https://api.maritime.sh',   // or MARITIME_API_URL
  timeout: 60_000,                      // per-request ms
  maxRetries: 2,                        // network + 5xx/429
})

Retries are safe by construction: GET/DELETE retry on any transient failure; writes retry only on network errors and 429/503 (never a 5xx that might have applied).

Agents

Access via maritime.agents (TS) / client.agents (Python).

Method	Does
create(params)	Create an agent and start its deploy. Prefer `template`: a bare framework yields a broken image.
provision({externalId, …})	Idempotent get-or-create by `externalId`. The recommended per-customer entry point.
get(id)	Fetch one agent.
list({externalId?, name?})	List agents, optionally filtered.
chat(id, message, opts?)	Send a message, wait for the reply. Auto-wakes a sleeping agent.
start / stop / sleep / restart(id)	Lifecycle transitions.
setEnv(id, key, value, {secret})	Upsert an env var (secrets encrypted at rest).
listEnv(id) / deleteEnv(id, key)	Read / remove env vars.
reloadEnv(id)	Push env changes into the running container.
logs(id, {limit?, level?})	Recent log entries.
delete(id)	Tear down the agent (container + volume + network).

create / provision parameters

Param	Type	Notes
name	string	Unique per account. Required.
template	string	openclaw · zeroclaw · hermes · openclaw_identity · … (see frameworks)
externalId	string	Your own id for this agent. Filterable; idempotency key for `provision`.
instructions	string	Plain-English persona / system prompt.
env	{key,value,secret}[]	Seed env vars. Secrets encrypted at rest.
idleTtlSeconds	number	Idle seconds before auto-sleep. 0 = always-on.

// Idempotent per-customer provisioning (recommended)
const agent = await maritime.agents.provision({
  externalId: `customer_${userId}`,
  name: `assistant-${userId}`,
  template: 'openclaw',
})

const { response } = await maritime.agents.chat(agent.id, 'Hello')
await maritime.agents.setEnv(agent.id, 'STRIPE_KEY', 'sk_live_...', { secret: true })
await maritime.agents.sleep(agent.id)
await maritime.agents.delete(agent.id)

Keys

Mint scoped API keys programmatically. Minting requires the caller's key to carry the manage scope.

Method	Does
create({name, scopes?, expiresInDays?})	Mint a key. The raw key is returned once.
list()	List your keys (raw values never returned again).
revoke(id)	Revoke a key.

const worker = await maritime.keys.create({ name: 'chat-worker', scopes: ['deploy'] })
// worker.rawKey is shown once. Store it now.

Webhooks

Receive signed lifecycle events instead of polling. See the webhooks section of the guide for signature verification.

Method	Does
create({url, events?})	Subscribe a URL. Returns the signing `secret` once.
list()	List subscriptions.
test(id)	Deliver a synthetic ping.
delete(id)	Remove a subscription.

Events: agent.deployed · agent.error · agent.sleeping · agent.woken · agent.restarted · agent.stopped.

Errors

Every failure is a subclass of MaritimeError. API errors expose .status and .detail.

Class	When
MaritimeAuthError	401 / 403: bad or under-scoped key
MaritimePaymentRequiredError	402: wallet needs funding
MaritimeNotFoundError	404: no such agent (or not yours)
MaritimeConflictError	409: name already taken
MaritimeRateLimitError	429: rate limited
MaritimeAPIError	any other non-2xx
MaritimeConnectionError	never reached Maritime (network / timeout)

from maritime import MaritimeAPIError

try:
    client.agents.get("nope")
except MaritimeAPIError as err:
    print(err.status, err.detail, err.request_id)