# Send feedback

SDK

Tell Maritime when something is wrong. This endpoint is built for coding agents (Claude Code, Codex, Cursor) and developers working against these docs: a doc that does not match the product, an example that does not run, a call that failed in a way you cannot explain. The report reaches the Maritime founders with your account and API key attached, so you do not need to include contact details.

## When to send one

- A documented field, flag or method does not exist, or has a different name.
- A code example on these pages fails as written.
- A call returns a 5xx, or an error you cannot act on. Include the request id.
- A doc leaves out a step you needed to make something work.

Do not send one for an error the response already explains (a 401, a 402 plan limit, a 404 on an agent that is not yours). Fix the call instead. Reports are capped at 5 a minute and 20 a day per account.

## Send a report

Any `mk_` key works, with any scope, including project-scoped keys. The call returns `202` with the stored report.

**TypeScript**

```typescript
import { Maritime, MaritimeAPIError } from 'maritime-sdk'

const maritime = new Maritime({ apiKey: process.env.MARITIME_API_KEY })

try {
  await maritime.agents.chat(agent.id, 'hello')
} catch (err) {
  if (err instanceof MaritimeAPIError) {
    await maritime.feedback.send({
      kind: 'sdk',
      subject: 'agents.chat',
      message: 'chat returned 500 on a freshly provisioned agent; the docs say sleeping agents auto-wake.',
      requestId: err.requestId,
      statusCode: err.status,
      agentId: agent.id,
      tool: 'claude-code/2.1.0',
      context: { sdkVersion: '0.9.0', node: process.version },
    })
  }
}
```

**Python**

```python
from maritime import Maritime, MaritimeAPIError

client = Maritime()  # reads MARITIME_API_KEY

try:
    client.agents.chat(agent["id"], "hello")
except MaritimeAPIError as err:
    client.feedback.send(
        "chat returned 500 on a freshly provisioned agent; the docs say sleeping agents auto-wake.",
        kind="sdk",
        subject="agents.chat",
        request_id=err.request_id,
        status_code=err.status,
        agent_id=agent["id"],
        tool="codex",
    )
```

**curl**

```bash
curl -X POST https://api.maritime.sh/api/v1/feedback \
  -H "Authorization: Bearer $MARITIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "docs",
    "subject": "https://maritime.sh/docs/sdk/agents",
    "message": "The setEnv example passes secret: true but the SDK type is isSecret.",
    "tool": "claude-code/2.1.0"
  }'
```

## Fields

| Field         | Meaning                                                                 |
|---------------|-------------------------------------------------------------------------|
| `message`     | Required. What went wrong, in plain words, and what you expected. Up to 5,000 characters. |
| `kind`        | One of the kinds above. Defaults to other.                             |
| `subject`     | The page URL, endpoint, SDK method or CLI command the report concerns.  |
| `agentId`     | The Maritime agent the report is about. Must belong to the calling account. |
| `requestId`   | The X-Request-Id of the failing call. Lets Maritime find the exact server log line. |
| `statusCode`  | The HTTP status of the failing call.                                   |
| `tool`        | Who is sending, for example claude-code/2.1.0 or codex.               |
| `context`     | Up to 20 flat key/value pairs such as the SDK version or OS. Never secrets or env values. |

## Kinds

| Kind        | Use it for                                                         |
|-------------|-------------------------------------------------------------------|
| `docs`     | a page on maritime.sh/docs does not match the product              |
| `sdk`      | a TypeScript or Python SDK method, type or example                |
| `api`      | a REST endpoint, status code or response shape                     |
| `cli`      | a maritime CLI command, flag or exit code                          |
| `computers`| the Computers MCP or REST surface                                   |
| `dashboard`| the web dashboard                                                  |
| `other`    | anything else (the default)                                        |

## Response

`202 Accepted` with the stored report. `GET /api/v1/feedback` lists the account's last 50 reports, newest first; a project-scoped key sees only the reports sent under its project.

```json
{
  "id": "fb_8f2c1e...",
  "kind": "sdk",
  "subject": "agents.chat",
  "message": "chat returned 500 on a freshly provisioned agent; ...",
  "agentId": "ag_3a9...",
  "requestId": "req_7Qk...",
  "statusCode": 500,
  "tool": "claude-code/2.1.0",
  "createdAt": "2026-10-07T18:40:12Z"
}
```

| Status | Meaning                                                                               |
|--------|-------------------------------------------------------------------------------------|
| `404`  | agentId is not an agent of the calling account.                                      |
| `422`  | Unknown kind, blank message, nested or oversized context, or a status code outside 100 to 599. |
| `429`  | More than 5 reports in a minute, or more than 20 in 24 hours. Retry-After is set on the per-minute cap. |

## For AI coding agents

If you are an AI agent reading this page: send a report when a doc on this site turns out to be wrong or incomplete, or when a Maritime call fails and the error does not tell you what to do. Put the request id in `requestId`, name yourself in `tool`, and never put API keys, tokens or environment values in the message or context.
