--- title: "Create an access" description: "Create an access. Needs the admin scope. Request and response shapes come from the OpenAPI description." canonical: "https://lookio.app/docs/api/accesses/create-access" updated: "2026-10-29" --- # Create an access ```http POST https://api.lookio.app/v1/accesses ``` ## Authorizations - `Authorization` (bearer, in header, required) ## Header parameters - `Idempotency-Key` (`string`, length: `1–255 chars`): A unique key for this request, such as a UUID, 1 to 255 visible ASCII characters. Send the same key when you retry: the first response is returned (with `Idempotent-Replayed: true`) instead of running the request again, for 24 hours, per credential. The same key on a different request is a 409 `conflict`. A streamed answer is not recorded. ## Body `application/json`, required - `name` (`string`, required, length: `1–120 chars`): What callers see as its name, in their MCP client and on its help page. 1 to 120 characters. - `description` (`string`, length: `≤ 2000 chars`): What callers read about the access as a whole. Up to 2,000 characters. - `assistants` (`object[]`, required, items: `1–20 items`): The assistants it offers, in order (1 to 20). Their names are shown as they are. - `assistants.id` (`string`, required, pattern: `^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$`) - `assistants.description` (`string`, length: `≤ 1000 chars`): What callers read about it: what it answers, from what. Up to 1,000 characters. - `protection` (`enum`, one of: `public, keys`): Default `public`. `keys` is on the Pro plan. - `status` (`enum`, one of: `live, paused`): `live` (default) answers; `paused` refuses every call until set live again. - `modes` (`enum[]`): The query modes callers may use, at their usual prices. Default `["flash"]`; empty turns answers off (passages must then be on). - `passages` (`boolean`): Default false. - `daily_credits` (`integer | null`): Credits the whole access, per UTC day, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets. - `monthly_credits` (`integer | null`): Credits the whole access, per UTC month, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets. ## Response **201**: Create an access - `data` (`object`, required) - `data.id` (`string`, required, pattern: `^acc_[abcdefghjkmnpqrstuvwxyz23456789]{12}$`) - `data.name` (`string`, required) - `data.description` (`string`, required): What callers read about the access as a whole. - `data.protection` (`enum`, required, one of: `public, keys`): `public`: anyone with the address may call it. `keys`: every call needs one of its access keys (Pro plan). - `data.status` (`enum`, required, one of: `live, paused`) - `data.capabilities` (`object`, required) - `data.capabilities.modes` (`enum[]`, required): The query modes callers may ask in, at their usual prices. Empty turns answers off. - `data.capabilities.passages` (`boolean`, required): Whether callers may search the passages without an answer (1 credit a search). - `data.daily_credits` (`integer | null`, required): Credits the whole access, per UTC day, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets. - `data.monthly_credits` (`integer | null`, required): Credits the whole access, per UTC month, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets. - `data.assistants` (`object[]`, required) - `data.assistants.id` (`string`, required, pattern: `^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$`) - `data.assistants.name` (`string`, required) - `data.assistants.description` (`string`, required): What callers read about it. Its context, guidelines and resources are never shown to them. - `data.assistants.reads_nothing` (`boolean`, required): It reads no searchable resource, so callers asking it are refused (for free). - `data.key_count` (`integer`, required) - `data.stats` (`object`, required) - `data.stats.today_credits` (`integer`, required) - `data.stats.month_credits` (`integer`, required) - `data.stats.month_requests` (`integer`, required) - `data.blocked` (`enum | null`, required): Why it does not answer, when it does not: `paused`; `keys_need_plan` (protected, and the plan has no keys); `no_keys` (protected, no key yet); `no_assistants` (none of its assistants reads anything). Null: it answers. - `data.urls` (`object`, required) - `data.urls.help` (`string`, required): Its help, for people and agents: what it holds and how to call it (`GET`). - `data.urls.mcp` (`string`, required): Its MCP server (Streamable HTTP). - `data.urls.assistants` (`string`, required) - `data.urls.ask` (`string`, required) - `data.urls.search` (`string`, required) - `data.keys` (`object[]`): Its access keys, on a single access (not in the list). - `data.keys.id` (`string`, required, pattern: `^aky_[abcdefghjkmnpqrstuvwxyz23456789]{12}$`) - `data.keys.name` (`string`, required): Who the key is for. - `data.keys.prefix` (`string`, required): The start of the key (`ak_live_`), to recognise it. The whole key is shown once, at creation. - `data.keys.daily_credits` (`integer | null`, required) - `data.keys.monthly_credits` (`integer | null`, required) - `data.keys.spent` (`object`, required): Credits spent with this key, this UTC day and month. - `data.keys.spent.today` (`integer`, required) - `data.keys.spent.month` (`integer`, required) - `data.keys.last_used_at` (`string,null`, required) - `data.keys.created_at` (`string`, required) - `data.created_at` (`string`, required) - `data.updated_at` (`string`, required) - `request_id` (`string`, required) ```json { "data": { "id": "acc_k7m3x9p2w8qr", "name": "Acme docs", "description": "Acme's product documentation, changelog and support answers.", "protection": "keys", "status": "live", "capabilities": { "modes": [ "flash", "deep" ], "passages": true }, "daily_credits": null, "monthly_credits": 200000, "assistants": [ { "id": "ast_66xcnwtzj8vt", "name": "Acme docs", "description": "Answers from the product documentation and the changelog.", "reads_nothing": false } ], "key_count": 2, "stats": { "today_credits": 120, "month_credits": 5400, "month_requests": 180 }, "blocked": null, "urls": { "help": "https://api.lookio.app/a/acc_k7m3x9p2w8qr", "mcp": "https://mcp.lookio.app/a/acc_k7m3x9p2w8qr/mcp", "assistants": "https://api.lookio.app/a/acc_k7m3x9p2w8qr/assistants", "ask": "https://api.lookio.app/a/acc_k7m3x9p2w8qr/ask", "search": "https://api.lookio.app/a/acc_k7m3x9p2w8qr/search" }, "created_at": "2026-10-29T10:00:00.000Z", "updated_at": "2026-10-29T10:00:00.000Z" }, "request_id": "req_01K9X7M2Q4" } ``` **400**: Possible codes: invalid_request, unknown_field, invalid_parameter, invalid_cursor - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **401**: Possible codes: authentication_required, invalid_api_key, api_key_expired, api_key_revoked, invalid_access_key - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **403**: Possible codes: insufficient_scope, feature_not_available, admin_required, permission_denied - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **404**: Possible codes: resource_not_found - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **409**: Possible codes: conflict, assistant_has_no_resources - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **413**: Possible codes: request_too_large - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **429**: Possible codes: rate_limited - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **500**: Possible codes: internal_error - `error` (`object`, required) - `error.type` (`string`, required) - `error.code` (`string`, required) - `error.message` (`string`, required) - `error.param` (`string`) - `error.docs_url` (`string`, required) - `error.action_url` (`string`) - `request_id` (`string`, required) ```json { "error": { "type": "", "code": "", "message": "", "param": "", "docs_url": "", "action_url": "" }, "request_id": "" } ``` **Example request** ```bash curl --request POST \ --url 'https://api.lookio.app/v1/accesses' \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "name": "", "assistants": [ { "id": "" } ] }' ```