> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Authentication, access tiers, rate limiting, and conventions for the Axiom Overwatch REST API — the programmatic interface to maritime risk and trade data.

The Axiom Overwatch API exposes 70+ endpoints across vessel tracking, risk intelligence, commodity flows, satellite imagery, P\&I coverage, trade flows, and more.

## Base URL

```
https://axiomoverwatch.io/api/v1
```

## Authentication

Most read-only endpoints are open to the public. Endpoints that return user-specific data, mutating endpoints, and high-volume reads require an API key.

A small public-tier slice — the [single-vessel latest-position lookup](/overwatch/api/vessels#get-api-v1-ais-provider-imo-location-latest) — is fully open, requires no key, ships JSON-LD attribution, and has its own [OpenAPI 3.1 spec](https://axiomoverwatch.io/openapi/positions.yaml) suitable for citation by journalists, academics, and AI ingestion pipelines.

Pass the key via the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/positions?port=houston
```

Generate keys in **Settings → API Keys** in the Overwatch dashboard.

## Access tiers

| Plan                  | Rate limit    | History depth | Features                                                        |
| --------------------- | ------------- | ------------- | --------------------------------------------------------------- |
| **Free**              | 60 req/min    | 7 days        | Public endpoints, ports, basic positions                        |
| **Starter**           | 600 req/min   | 30 days       | All read endpoints, exports up to 1k rows                       |
| **Pro**               | 6,000 req/min | Full          | All endpoints, webhooks, priority sync, 10k row exports         |
| **Supply Chain Risk** | Custom        | Full          | Pro + dark fleet alerts, custom risk scoring, dedicated support |

See `/api/v1/billing/plans` for live pricing.

## Rate limiting

Rate limit headers are returned on every response:

* `X-RateLimit-Limit` — your tier's per-minute limit
* `X-RateLimit-Remaining` — requests remaining in the current window
* `X-RateLimit-Reset` — UTC epoch seconds when the window resets

When you exceed the limit, you'll get HTTP 429 with a `Retry-After` header.

## Response format

All endpoints return JSON with the data nested under a top-level key matching the resource (e.g. `vessels`, `positions`, `events`). Errors return:

```json theme={null}
{ "error": "human-readable message", "code": "machine_readable_code" }
```

## Methodology

Every endpoint that returns inferred or modeled data (cargo estimates, risk scores, dark fleet detections, draft anomalies) includes:

* A `confidence` or `tier` field indicating signal strength
* A `methodology` link in the response or in the endpoint docs

For modeling specifics, see the [Methodology](/overwatch/methodology/cargo-validation) section.

## Port slugs

Ports are referenced by slug (e.g. `houston`, `santos`, `singapore`, `rotterdam`). Get the full list from `GET /api/v1/ports`.

## Quick start

```bash theme={null}
# 1. List monitored ports
curl https://axiomoverwatch.io/api/v1/ports

# 2. Get latest vessel positions at a port
curl https://axiomoverwatch.io/api/v1/positions?port=houston

# 3. Pull risk-scored vessels (auth required for full data)
curl -H "X-API-Key: YOUR_KEY" \
  https://axiomoverwatch.io/api/v1/risk/vessels?tier=critical
```

## SDK + MCP

* **Python**: `pip install axiom-overwatch` — see [SDKs & MCP](/overwatch/api/sdk).
* **MCP server**: lets Claude / GPT / any MCP-compatible AI agent query Overwatch directly.

## Where to from here

Browse the endpoints by category in the sidebar, or jump to the most-used groups:

<Columns cols={2}>
  <Card title="Vessels & Positions" href="/overwatch/api/vessels">Real-time AIS positions and vessel registry</Card>
  <Card title="Risk Intelligence" href="/overwatch/api/risk">Dark fleet, STS, loitering, identity changes</Card>
  <Card title="Trade Flows" href="/overwatch/api/trade-flows">Bilateral commodity trade, mirror discrepancies, sanctions</Card>
  <Card title="Emissions" href="/overwatch/api/emissions">CSRD/SEC Scope 3 maritime emissions reports</Card>
</Columns>