Conventions

Requests and responses

• Send JSON with Content-Type: application/json. A body without the header is accepted if it parses.
• Fields are snake_case, in requests and responses.
• An id is a type prefix and twelve random lowercase letters or digits: ast_k7m3x9p2w8qr is an assistant, res_h4n8c2v6y9tk a resource. A rename does not change it. A widget has the same wdg_… id in the API, the snippets and the hosted address. Treat ids as opaque strings.
• Timestamps are ISO 8601 strings in UTC.
• A JSON body is at most 1 MB. Send a file with the upload call.
• A trailing slash is allowed: /v1/account/ is /v1/account.
• Responses carry Cache-Control: no-store.

A success wraps the result:

{
  "data": { },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

A list also has has_more, next_cursor and limit. Each endpoint page shows the shape of data.

Inputs: forgiving, then strict

• A missing optional field takes its documented default.
• A limit above the maximum becomes the maximum. The response gives the limit used.
• An unknown field in a JSON body fails with unknown_field, at any depth (for example rules.exlude). The message gives the closest valid name: for followTags, “Did you mean ‘follow_tags’?”.
• Lookio ignores an unknown query parameter, so a tracking parameter from a proxy does not break a call. But a filter with a typo returns an unfiltered result.
• The error gives only the first problem.

Pagination

Lists of resources use a cursor.

curl "https://api.lookio.app/v1/resources?limit=50" \
  -H "Authorization: Bearer $LOOKIO_API_KEY"

Results come newest first. While has_more is true, call again with cursor set to next_cursor. A cursor that matches nothing fails with invalid_cursor.

Other lists (assistants, tags, members) come whole, in one response.

Idempotency

Networks fail, and automation tools retry. Without protection, a retried import makes a second resource, and a retried question is charged twice.

Add an Idempotency-Key header to a POST. Lookio runs the request once. A repeat with the same key returns the first response, with the header Idempotent-Replayed: true.

curl https://api.lookio.app/v1/assistants/ASSISTANT_ID/query \
  -H "Authorization: Bearer $LOOKIO_API_KEY" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{ "question": "How long do I have to return an item?" }'

The rules:

• The key is 1 to 255 visible ASCII characters. Use a UUID. Make a new key for each request, and use it again only for retries of that request.
• A key belongs to one credential and lives 24 hours.
• The same key on a different request (method, path, query or body) fails with conflict.
• A retry while the first request runs fails with conflict. Wait a few seconds and retry.
• Lookio replays a refusal (4xx) like any response. It does not keep a 5xx or a 429, so the next retry runs again.
• Lookio keeps a response only if it is JSON and under 256 KB.
• For a file upload, Lookio compares the name, size and query, not the bytes.

The CLI sends a new Idempotency-Key with each POST, and the same key on its automatic retries.

Request IDs

Every response has an X-Request-Id header, and JSON responses a request_id field: req_ and 32 hex characters. Lookio makes it. You cannot send one.

Log it. It identifies the request without showing your key or your content. Support asks for it.

Read after write

Every response has an X-D1-Bookmark header. Send the last one you got as X-D1-Bookmark on your next request. Lookio then reads data at least as new as your last write. Without it, a read just after a write can sometimes come from a copy that is not up to date. Lookio ignores a bookmark that is not valid.

Asynchronous work

Importing is asynchronous. A new resource is queued. Poll GET /v1/resources/{resource_id} until status is ready or failed, then stop. An assistant answers only from ready resources.

Costs and limits

Only asking an assistant and searching its passages (1 credit) spend credits. The response gives its credit_cost.

Importing is free of credits, but it has limits. Lookio refuses a call over a limit before it stores anything.

See Word allowance and Pages read each month. GET /v1/account returns the limits of your plan. The Resources page of the app shows your use.