Skip to main content
This guide walks you from zero to a running analysis in a handful of curl commands.
Prefer a CLI over raw HTTP? Install lymo and run lymo setup && lymo summary latest — same API, with browser-based sign-in, named profiles, and built-in MCP support for agents.

​
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. 
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: 
curl "$LYMO_BASE/health"
# → { "data": { "status": "ok" }, "meta": { "request_id": "req_..." } }
Then confirm your key is accepted: 
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

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. 
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. 
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: 
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 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 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): 
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 for the full cache semantics, TTL, and when to send a fresh key.