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

# Quickstart

> Make your first authenticated request

This guide walks you from zero to a running analysis in a handful of `curl` commands.

<Tip>
  Prefer a CLI over raw HTTP? Install [`lymo`](/en/guides/cli) and run `lymo setup && lymo summary latest` — same API, with browser-based sign-in, named profiles, and built-in MCP support for agents.
</Tip>

## 1. Get an API key

In the Lymo web app, go to **Settings → Platform** and click **Create key**. Copy the generated key (starts with `lymo_`) — it is shown once.

```bash theme={null}
export LYMO_KEY=lymo_xxxxxxxxxxxxxxxx
export LYMO_BASE=https://platform.lymo.jp
```

`LYMO_BASE` stops at the host so the same variable works for both the unversioned `/health` probe and every versioned `/v1/*` endpoint.

## 2. Verify the connection

Start with a no-auth health check to confirm you can reach the API:

```bash theme={null}
curl "$LYMO_BASE/health"
# → { "data": { "status": "ok" }, "meta": { "request_id": "req_..." } }
```

Then confirm your key is accepted:

```bash theme={null}
curl "$LYMO_BASE/v1/members/me" \
  -H "Authorization: Bearer $LYMO_KEY"
```

If `/health` returns but `/v1/members/me` does not, the problem is authentication (wrong key, revoked, or missing scope). If `/health` itself fails, you have a network or base-URL problem.

## 3. List your videos

```bash theme={null}
curl "$LYMO_BASE/v1/videos?limit=5" \
  -H "Authorization: Bearer $LYMO_KEY"
```

Pick a video ID from the response and save it. IDs are UUIDs — there is no resource prefix.

```bash theme={null}
export VIDEO=a1b2c3d4-5e6f-7890-abcd-ef0123456789
```

## 4. Trigger an analysis

Analyses are asynchronous — `POST` creates the resource and returns `201` immediately with `status: "processing"`. Poll or subscribe to a webhook for completion.

```bash theme={null}
RESPONSE=$(curl -s -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY")

echo "$RESPONSE" | jq .
# {
#   "data": {
#     "id": "b2c3d4e5-...",
#     "status": "processing",
#     "video_id": "a1b2c3d4-...",
#     "started_at": null,
#     "finished_at": null,
#     "created_at": "2026-04-24T12:34:56.000Z",
#     "updated_at": "2026-04-24T12:34:56.000Z"
#   },
#   "meta": { "request_id": "req_..." }
# }

ANALYSIS=$(echo "$RESPONSE" | jq -r .data.id)
echo "Started analysis $ANALYSIS"
```

Poll for the result:

```bash theme={null}
curl "$LYMO_BASE/v1/videos/$VIDEO/analyses/$ANALYSIS" \
  -H "Authorization: Bearer $LYMO_KEY"
# → { "data": { "status": "processing" | "completed" | "failed", "result": {...}? }, "meta": {...} }
```

When `status` becomes `completed`, a `result` object carrying the analysis output appears on the same resource. See [Async pattern](/en/guides/async-pattern) for the full polling loop, idempotency, and how to switch from polling to webhooks.

## Error handling

All errors share a consistent shape. The codes you're most likely to see during setup are `unauthorized` (401), `forbidden` (403), `not_found` (404), `validation_failed` (422), and `rate_limited` (429). For the full table — including recovery steps and cross-tenant 404 semantics — see the [Errors](/en/guides/errors) guide.

## Idempotency

`POST` requests accept an `Idempotency-Key` header. Reuse it whenever a network retry could cause duplicate work (e.g. an ambiguous client timeout on analysis creation):

```bash theme={null}
curl -X POST "$LYMO_BASE/v1/videos/$VIDEO/analyses" \
  -H "Authorization: Bearer $LYMO_KEY" \
  -H "Idempotency-Key: $(openssl rand -hex 16)"
```

See [Async pattern → Idempotency](/en/guides/async-pattern#idempotency) for the full cache semantics, TTL, and when to send a fresh key.