> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cargovision.app/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cargovision.app/_mcp/server.

# Quickstart

This guide signs in with an email account and lists the containers visible to that account. It uses `curl`, but any HTTP client works.

| Environment       | Base URL                      |
| ----------------- | ----------------------------- |
| Production        | `https://api.cargovision.app` |
| Local development | `http://localhost:8080`       |

Every endpoint lives under the `/v1` prefix, for example `https://api.cargovision.app/v1/containers`. The health probes `/health` and `/ready` are the only unversioned routes.

#### Get an account

Accounts are invite-only. Ask a Cargovision administrator for an invite, accept it, and set a password. Google sign-in is also available through the web dashboard.

#### Sign in

Send your credentials to the login endpoint and keep the returned session cookie.

```bash
curl -sS -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"email":"operator@example.com","password":"your-password"}' \
  https://api.cargovision.app/v1/user/auth/email/login
```

A successful login returns `200` with your email and role, and sets an HttpOnly `token` cookie that holds your JWT:

```json
{
  "status": "success",
  "message": "Login Success",
  "data": { "email": "operator@example.com", "role": "operator" }
}
```

#### List your containers

Send the cookie back on the next request:

```bash
curl -sS -b cookies.txt \
  "https://api.cargovision.app/v1/containers?page=1&limit=20"
```

The response uses the standard `{ success, data }` envelope:

```json
{
  "success": true,
  "data": {
    "containers": [
      { "containerNumber": "MSCU1234566", "status": "ANALYZED", "aiDecision": { "status": "CLEARED" } }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 1, "pages": 1 }
  }
}
```

#### Use a bearer token in scripts

Server-side scripts can send the same JWT as a bearer token instead of a cookie. Read the `token` value from `cookies.txt` and pass it in the `Authorization` header:

```bash
TOKEN=$(awk '$6 == "token" { print $7 }' cookies.txt)
curl -sS -H "Authorization: Bearer $TOKEN" \
  https://api.cargovision.app/v1/containers/stats
```

Bearer requests skip the browser-origin check that applies to cookie-authenticated writes. See [Authentication](/authentication).

## Next steps

#### [Authentication](/authentication)

Session lifetime, roles, and edge-device API keys.

#### [Inspection lifecycle](/inspection-lifecycle)

What container statuses, severities, and AI decisions mean.

#### [Edge device integration](/edge-integration)

Push scan results from an edge device.

#### [API reference](/api-reference)

Every endpoint, parameter, and schema.