{ "openapi": "3.1.0", "info": { "title": "Lookio API", "version": "1.0.0", "description": "Lookio answers questions from your own knowledge. Add resources (texts, files, web pages, whole sites kept in sync), give them to assistants, and ask those assistants questions, from a script, an automation, a terminal or an AI agent.\n\nImporting costs no credits. A question costs 30 credits in the default mode, whatever the answer's length (Eco 10, Flash 30 credits (the default), Deep 80), even when the resources hold no answer; an assistant that reads no resource is refused with the error `assistant_has_no_resources`, before any credit is held. Every POST accepts an `Idempotency-Key` header: a retried request returns the first response, marked `Idempotent-Replayed: true`, and is not charged twice. Every response carries an `X-Request-Id`: quote it when contacting support. Requests are limited to 240 a minute per credential with a burst ceiling of 40 every 10 seconds (`RateLimit-Policy` says so on every response); past it the answer is 429 with `Retry-After`. Call `GET /v1/account` first: `credential.scopes` lists what this credential may do.", "contact": { "name": "Lookio", "url": "https://lookio.app" } }, "servers": [ { "url": "https://api.lookio.app", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An API key (`sk_live_…`) created in the workspace settings, or an OAuth access token. Never place a credential in a URL or query string." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } }, "headers": { "XRequestId": { "description": "The id of this request, `req_…`. Quote it in a support request. Also in the body as `request_id`.", "schema": { "type": "string" } }, "RateLimitPolicy": { "description": "The credential's limits, `240;w=60, 40;w=10` (RFC 9331 policy: requests per window in seconds). The remaining quota is not reported.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } }, "IdempotentReplayed": { "description": "`true` when this is the stored response of an earlier request with the same `Idempotency-Key`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "schemas": { "Error": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "docs_url": { "type": "string" }, "action_url": { "type": "string", "format": "uri" } }, "required": [ "type", "code", "message", "docs_url" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "StreamStatusEvent": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "phase": { "type": "string", "enum": [ "searching", "reading", "answering" ] } }, "required": [ "phase" ], "additionalProperties": false }, "StreamDeltaEvent": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "text": { "type": "string", "description": "The next piece of the answer, in order." } }, "required": [ "text" ], "additionalProperties": false }, "StreamDoneEvent": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "answer": { "type": "string", "description": "Markdown. Citations appear as [1], [2]…" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "The cited resource. Empty for a public assistant of another workspace: its resources stay its own." }, "title": { "type": "string" }, "text": { "type": "string", "description": "The passage the answer relies on." }, "n": { "description": "The number the answer cites it by, as [1].", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "section": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "source": { "description": "The cited resource's source, when it has one.", "type": "string" } }, "required": [ "resource_id", "title", "text" ], "additionalProperties": false } }, "conversation_id": { "description": "The conversation this answer belongs to: pass it back as `conversation_id` to continue it. Null when nothing was stored (`store: false`).", "type": [ "string", "null" ] }, "message_id": { "description": "The id of this answer in the conversation. On an API key's conversation it is what `POST /v1/conversations/{conversation_id}/messages/{message_id}/feedback` takes (a person's own chats take no thumbs yet). Null when nothing was stored.", "type": [ "string", "null" ] }, "credit_cost": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this answer cost. A model answer costs its mode's fixed price." }, "credits_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "simulated": { "type": "boolean", "description": "True on a development deployment answering without a model." } }, "required": [ "answer", "citations", "conversation_id", "message_id", "credit_cost", "credits_remaining", "simulated" ], "additionalProperties": false }, "StreamErrorEvent": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "docs_url": { "type": "string" }, "action_url": { "type": "string", "format": "uri" } }, "required": [ "type", "code", "message", "docs_url" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false } }, "responses": { "Error400": { "description": "Possible codes: invalid_request, unknown_field, invalid_parameter, invalid_cursor", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Possible codes: authentication_required, invalid_api_key, api_key_expired, api_key_revoked, invalid_access_key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "WWW-Authenticate": { "description": "How to authenticate: `Bearer`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error402": { "description": "Possible codes: insufficient_credits", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Possible codes: insufficient_scope, feature_not_available, admin_required, permission_denied", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Possible codes: resource_not_found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error405": { "description": "Possible codes: method_not_allowed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Allow": { "description": "The methods this path answers.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "Possible codes: conflict, assistant_has_no_resources", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error413": { "description": "Possible codes: request_too_large", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error422": { "description": "Possible codes: request_too_large_for_plan", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Possible codes: rate_limited", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error500": { "description": "Possible codes: internal_error", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Possible codes: service_unavailable", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "x-scopes": { "account:read": "See your workspace, plan, and credit balance.", "usage:read": "See your credit usage over time, and the log of every answer: when, which assistant, through which channel, what it cost. Not what was asked.", "resources:read": "See your resources, their indexed content and their import status, including the pages of a site, and the log of every indexing with its errors.", "resources:write": "Add resources (files, web pages, whole sites, text), edit them, re-index them and synchronise sites. Importing costs no credits.", "resources:delete": "Delete resources and everything indexed from them.", "assistants:read": "See the assistants you have access to and their settings.", "assistants:write": "Create and edit assistants and their widgets, choose the resources they answer from, and read the conversations people outside the workspace had with them (widget visitors, the users of your product). Deleting an assistant is a separate permission.", "assistants:delete": "Delete assistants. Their resources are kept.", "query": "Ask questions and read answers with sources. Each answer returned by the model spends the selected mode's fixed price, even if no source is found. Assistants with no resources are refused before a model call, at no cost. Rename or delete conversations and rate answers.", "admin": "Manage the Lookio permissions of the workspace's members and their access to assistants, and read the workspace's activity log (who changed what). Admins only.", "webhooks:write": "Create, edit and delete the webhooks that notify your systems when an import finishes or needs attention. Not available yet." }, "x-error-codes": [ { "code": "authentication_required", "status": 401, "type": "authentication_error", "docs_url": "https://lookio.app/docs/api/errors#authentication_required" }, { "code": "invalid_api_key", "status": 401, "type": "authentication_error", "docs_url": "https://lookio.app/docs/api/errors#invalid_api_key" }, { "code": "api_key_expired", "status": 401, "type": "authentication_error", "docs_url": "https://lookio.app/docs/api/errors#api_key_expired" }, { "code": "api_key_revoked", "status": 401, "type": "authentication_error", "docs_url": "https://lookio.app/docs/api/errors#api_key_revoked" }, { "code": "invalid_access_key", "status": 401, "type": "authentication_error", "docs_url": "https://lookio.app/docs/api/errors#invalid_access_key" }, { "code": "insufficient_scope", "status": 403, "type": "permission_error", "docs_url": "https://lookio.app/docs/api/errors#insufficient_scope" }, { "code": "feature_not_available", "status": 403, "type": "permission_error", "docs_url": "https://lookio.app/docs/api/errors#feature_not_available" }, { "code": "admin_required", "status": 403, "type": "permission_error", "docs_url": "https://lookio.app/docs/api/errors#admin_required" }, { "code": "permission_denied", "status": 403, "type": "permission_error", "docs_url": "https://lookio.app/docs/api/errors#permission_denied" }, { "code": "invalid_request", "status": 400, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#invalid_request" }, { "code": "unknown_field", "status": 400, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#unknown_field" }, { "code": "invalid_parameter", "status": 400, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#invalid_parameter" }, { "code": "invalid_cursor", "status": 400, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#invalid_cursor" }, { "code": "request_too_large", "status": 413, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#request_too_large" }, { "code": "method_not_allowed", "status": 405, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#method_not_allowed" }, { "code": "resource_not_found", "status": 404, "type": "not_found_error", "docs_url": "https://lookio.app/docs/api/errors#resource_not_found" }, { "code": "conflict", "status": 409, "type": "conflict_error", "docs_url": "https://lookio.app/docs/api/errors#conflict" }, { "code": "assistant_has_no_resources", "status": 409, "type": "conflict_error", "docs_url": "https://lookio.app/docs/api/errors#assistant_has_no_resources" }, { "code": "insufficient_credits", "status": 402, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#insufficient_credits" }, { "code": "request_too_large_for_plan", "status": 422, "type": "invalid_request_error", "docs_url": "https://lookio.app/docs/api/errors#request_too_large_for_plan" }, { "code": "rate_limited", "status": 429, "type": "rate_limit_error", "docs_url": "https://lookio.app/docs/api/errors#rate_limited" }, { "code": "internal_error", "status": 500, "type": "api_error", "docs_url": "https://lookio.app/docs/api/errors#internal_error" }, { "code": "service_unavailable", "status": 503, "type": "api_error", "docs_url": "https://lookio.app/docs/api/errors#service_unavailable" } ], "paths": { "/v1/account": { "get": { "operationId": "getAccount", "x-surface-coverage": { "cli": "lookio account", "mcp": "get_account" }, "summary": "Retrieve the authenticated workspace", "description": "The workspace, its plan and limits (seats, words allowed), the credential making the call with its scopes, and what Lookio offers: the query modes with their credit prices, the file formats it reads and whether this credential can keep conversations. Call this first: one request tells you what you may do.", "tags": [ "account" ], "parameters": [], "security": [ { "bearerAuth": [ "account:read" ] } ], "responses": { "200": { "description": "Retrieve the authenticated workspace", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string" } }, "required": [ "id", "name", "slug", "plan" ], "additionalProperties": false }, "credit_balance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "entitlements": { "type": "object", "properties": { "seats": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Members the plan allows. Null is unlimited." }, "word_allowance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Words the workspace may keep indexed on its plan. Null is unlimited. `GET /v1/usage` says how many are stored." }, "assistants": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Assistants the plan allows. Null is unlimited. Creating one more is refused with `feature_not_available`." }, "widgets": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Widgets the plan allows. Null is unlimited. Creating one more is refused with `feature_not_available`." }, "pages_per_month": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Pages read a month (file pages and web pages, new or changed only). Null is unlimited. `GET /v1/usage` says how many are used." } }, "required": [ "seats", "word_allowance", "assistants", "widgets", "pages_per_month" ], "additionalProperties": false }, "credential": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "api_key", "oauth" ] }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "account:read", "usage:read", "resources:read", "resources:write", "resources:delete", "assistants:read", "assistants:write", "assistants:delete", "query", "admin", "webhooks:write" ] } }, "created_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "name", "prefix", "scopes", "created_at", "expires_at" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "query_modes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "label": { "type": "string" }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits a question costs in this mode, whatever the answer and its length." }, "description": { "type": "string" }, "available": { "type": "boolean" } }, "required": [ "id", "label", "credits", "description", "available" ], "additionalProperties": false } }, "default_query_mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "supported_formats": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "extensions": { "type": "array", "items": { "type": "string" } }, "max_bytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The largest file of this family, in bytes." } }, "required": [ "id", "label", "extensions", "max_bytes" ], "additionalProperties": false } }, "conversations": { "type": "boolean", "description": "True when this credential's answers are kept in conversations it can continue with `conversation_id`: a person's chats, and an API key's conversations (unless a question sends `store: false`)." }, "webhooks": { "type": "boolean" } }, "required": [ "query_modes", "default_query_mode", "supported_formats", "conversations", "webhooks" ], "additionalProperties": false } }, "required": [ "workspace", "credit_balance", "entitlements", "credential", "capabilities" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "rate_limited", "internal_error" ] } }, "/v1/feedback": { "post": { "operationId": "submitFeedback", "x-surface-coverage": { "cli": "lookio feedback send", "mcp": "send_feedback", "cliInputs": { "observed_problem": { "inputs": [ "--problem" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "related_action": { "inputs": [ "--action" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "ai_model": { "inputs": [ "--model" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "agent_harness": { "inputs": [ "--harness" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Submit feedback about using Lookio", "description": "Record open-text feedback about an unexpected result, confusing behaviour, an error, or something you wish worked differently in the API, CLI or MCP server. Describe the situation, what you observed, and what you expected instead. If known, include the related tool, API operation or CLI command, the AI model and the agent harness. Do not include API keys, tokens, signed URLs or full file contents. Costs no credits and does not change your workspace.", "tags": [ "feedback" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [] } ], "responses": { "201": { "description": "Submit feedback about using Lookio", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "feedback_id": { "type": "string" }, "received": { "type": "boolean", "const": true } }, "required": [ "feedback_id", "received" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "conflict", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "observed_problem": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What went wrong, was confusing, or should work differently." }, "situation": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What you were trying to do and what happened around the problem." }, "expected_solution": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What you expected Lookio to do, or how you would improve it." }, "related_action": { "description": "The MCP tool, API operation, or CLI command involved, if known.", "type": "string", "maxLength": 200 }, "ai_model": { "description": "The AI model used, if known. Do not guess.", "type": "string", "maxLength": 200 }, "agent_harness": { "description": "The agent client or harness used, if known, such as Claude Desktop or Cursor.", "type": "string", "maxLength": 200 } }, "required": [ "observed_problem", "situation", "expected_solution" ], "additionalProperties": false } } } } } }, "/v1/credits": { "get": { "operationId": "getCredits", "x-surface-coverage": { "cli": "lookio credits", "mcp": "get_credit_balance" }, "summary": "Retrieve the credit balance and every grant", "description": "The current balance plus each grant with its remaining amount and expiry. `next_refill_estimated_at` is derived from the latest monthly grant's expiry and is an estimate, not a guarantee: the refill runs on a cron pass after that moment.", "tags": [ "credits" ], "parameters": [], "security": [ { "bearerAuth": [ "account:read" ] } ], "responses": { "200": { "description": "Retrieve the credit balance and every grant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "balance": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "plan": { "type": "string" }, "monthly_allowance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "next_refill_estimated_at": { "type": [ "string", "null" ] }, "grants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "granted_at": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "amount", "used", "remaining", "granted_at", "expires_at" ], "additionalProperties": false } } }, "required": [ "balance", "plan", "monthly_allowance", "next_refill_estimated_at", "grants" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "rate_limited", "internal_error" ] } }, "/v1/usage": { "get": { "operationId": "getUsage", "x-surface-coverage": { "cli": "lookio usage", "mcp": "get_usage" }, "summary": "Retrieve credit usage over time", "description": "What the workspace's answers cost over a range, from the ledger of settled answers: answers and credits per day, week or month, and broken down by query mode, assistant, who asked (a person or an API key) and API key, plus the words stored and the pages extracted this month against the plan's allowances. With no parameters it returns the last 30 days. Granularity defaults to the range length: day up to 31 days, week up to 180, month beyond.", "tags": [ "usage" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "day", "week", "month" ] } } ], "security": [ { "bearerAuth": [ "usage:read" ] } ], "responses": { "200": { "description": "Retrieve credit usage over time", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "granularity": { "type": "string", "enum": [ "day", "week", "month" ] }, "totals": { "type": "object", "properties": { "answers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Answers settled, found or not." }, "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "answers", "credits_used" ], "additionalProperties": false }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "answers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Answers settled, found or not." }, "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "date", "answers", "credits_used" ], "additionalProperties": false } }, "by_mode": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string" }, "answers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Answers settled, found or not." }, "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "mode", "answers", "credits_used" ], "additionalProperties": false }, "description": "Per query mode. Besides the modes of `GET /v1/account`, it can list `search` (passage searches) and modes no longer offered, such as `europe` and `agent-lite`, kept for the history." }, "by_assistant": { "type": "array", "items": { "type": "object", "properties": { "assistant_id": { "type": [ "string", "null" ] }, "name": { "description": "Null when the assistant was deleted since.", "type": [ "string", "null" ] }, "answers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Answers settled, found or not." }, "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "assistant_id", "name", "answers", "credits_used" ], "additionalProperties": false } }, "by_origin": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "enum": [ "person", "api_key" ], "description": "`person`: someone asking from the app, the CLI or an MCP client. `api_key`: a technical identity." }, "answers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Answers settled, found or not." }, "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "origin", "answers", "credits_used" ], "additionalProperties": false } }, "by_api_key": { "type": "array", "items": { "type": "object", "properties": { "credential_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "answers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Answers settled, found or not." }, "credits_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "credential_id", "name", "answers", "credits_used" ], "additionalProperties": false } }, "words": { "type": "object", "properties": { "stored": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Words currently indexed in the workspace." }, "allowance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "What the plan allows. Null is unlimited." } }, "required": [ "stored", "allowance" ], "additionalProperties": false }, "pages": { "type": "object", "properties": { "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Pages extracted this calendar month (UTC): OCR pages and web pages read, new or changed only. Imports never spend credits." }, "allowance": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Pages the plan extracts a month. Null is unlimited." }, "resets_at": { "type": "string", "description": "When the count starts again (the first of next month, UTC)." } }, "required": [ "used", "allowance", "resets_at" ], "additionalProperties": false } }, "required": [ "from", "to", "granularity", "totals", "points", "by_mode", "by_assistant", "by_origin", "by_api_key", "words", "pages" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "invalid_parameter", "rate_limited", "internal_error" ] } }, "/v1/resources": { "get": { "operationId": "listResources", "x-surface-coverage": { "cli": "lookio resources list", "mcp": "list_resources", "cliInputs": { "q": { "inputs": [ "--query" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "List resources", "description": "The workspace's resources, newest first. Filter by `type`, `tag`, `status` (for instance `failed`) or `q`, a search in the title. Paginate with `cursor`: pass `next_cursor` from the previous page.", "tags": [ "resources" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "tag", "in": "query", "required": false, "schema": { "description": "Only resources carrying this tag.", "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "type", "in": "query", "required": false, "schema": { "description": "Only resources of this type.", "type": "string", "enum": [ "text", "file", "url", "site" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Only resources in this state, such as `failed` to find what needs a fix or `processing` to see what is still being read.", "type": "string", "enum": [ "queued", "processing", "ready", "failed", "stale", "ready_simulated" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "description": "Only resources whose title contains this text, without regard to case.", "type": "string", "minLength": 1, "maxLength": 100 } } ], "security": [ { "bearerAuth": [ "resources:read" ] } ], "responses": { "200": { "description": "List resources", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "file", "url", "site" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed", "stale", "ready_simulated" ], "description": "`queued` and `processing`: being read and indexed (pass `wait=true` or poll until it changes). `ready`: searchable. `failed`: see `status_detail`, then fix and call reindex." }, "status_detail": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source_url": { "description": "The page or site address, for `url` and `site` resources.", "type": [ "string", "null" ] }, "source": { "description": "Where it comes from, as shown with its citations.", "type": [ "string", "null" ] }, "site": { "anyOf": [ { "type": "object", "properties": { "rules": { "default": { "include": [], "exclude": [], "excluded_urls": [] }, "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } }, "required": [ "include", "exclude", "excluded_urls" ], "additionalProperties": false }, "schedule": { "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$", "description": "`manual` syncs only on request. Recurring schedules accept `daily`, `weekly`, `monthly`, or `every_N_days`, `every_N_weeks` and `every_N_months` (1-90 days, 1-52 weeks, 1-12 months). Recurring schedules require a paid plan." }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "rules", "schedule", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "A site's page rules and schedule; null for other types." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "type", "status", "status_detail", "tags", "source_url", "source", "site", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] }, "examples": { "default": { "value": { "data": [ { "id": "res_thk6smb5nvts", "title": "Refund policy", "type": "text", "status": "ready", "status_detail": null, "tags": [ "legal", "faq" ], "source_url": null, "source": "Employee handbook, 2026 edition", "site": null, "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "invalid_cursor", "rate_limited", "internal_error" ] }, "post": { "operationId": "createResource", "x-surface-coverage": { "cli": "lookio resources add-text", "mcp": "add_text_resource" }, "summary": "Add a text, a web page or a site", "description": "Creates a resource from a text (`type: \"text\"`), one web page (`\"url\"`) or a whole site (`\"site\"`, its pages chosen by `rules`). A site defaults to manual sync on Free and weekly sync on paid plans; recurring intervals require a paid plan. For a file, use POST /v1/resources/file. By default the resource comes back `queued` and is read and indexed in the background (seconds for a short text, file or page, minutes for a site). Pass `?wait=true` to wait up to 15 seconds for it to finish in one call, or poll `GET /v1/resources/{id}` (`?wait=true` works there too) until `status` is `ready` or `failed`. Importing costs no credits.", "tags": [ "resources" ], "parameters": [ { "name": "wait", "in": "query", "required": false, "schema": { "description": "Wait up to 15 seconds for reading and indexing to finish before returning. Short texts, files and pages usually come back `ready` (or `failed`) in one call; larger imports return their current status (`queued` or `processing`) when the window ends, never an error.", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "resources:write" ] } ], "responses": { "201": { "description": "Add a text, a web page or a site", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "file", "url", "site" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed", "stale", "ready_simulated" ], "description": "`queued` and `processing`: being read and indexed (pass `wait=true` or poll until it changes). `ready`: searchable. `failed`: see `status_detail`, then fix and call reindex." }, "status_detail": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source_url": { "description": "The page or site address, for `url` and `site` resources.", "type": [ "string", "null" ] }, "source": { "description": "Where it comes from, as shown with its citations.", "type": [ "string", "null" ] }, "site": { "anyOf": [ { "type": "object", "properties": { "rules": { "default": { "include": [], "exclude": [], "excluded_urls": [] }, "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } }, "required": [ "include", "exclude", "excluded_urls" ], "additionalProperties": false }, "schedule": { "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$", "description": "`manual` syncs only on request. Recurring schedules accept `daily`, `weekly`, `monthly`, or `every_N_days`, `every_N_weeks` and `every_N_months` (1-90 days, 1-52 weeks, 1-12 months). Recurring schedules require a paid plan." }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "rules", "schedule", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "A site's page rules and schedule; null for other types." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "type", "status", "status_detail", "tags", "source_url", "source", "site", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "res_thk6smb5nvts", "title": "Refund policy", "type": "text", "status": "queued", "status_detail": null, "tags": [ "legal", "faq" ], "source_url": null, "source": "Employee handbook, 2026 edition", "site": null, "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "conflict", "request_too_large_for_plan", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "text": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "The text itself, up to 100,000 characters. Markdown headings become sections." }, "tags": { "description": "Up to 30 tags of 60 characters. An assistant can follow a tag to use every resource carrying it.", "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "source": { "description": "Where this resource comes from, shown with every citation of it: a URL or a mention such as \"Employee handbook, 2026 edition\". Up to 500 characters; an empty string clears it.", "type": "string", "maxLength": 500 } }, "required": [ "type", "title", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "url" }, "url": { "type": "string", "minLength": 4, "maxLength": 2000, "description": "A public web page. Pages built in JavaScript are read too." }, "title": { "description": "Defaults to the page's own title once it is read.", "type": "string", "minLength": 1, "maxLength": 200 }, "tags": { "description": "Up to 30 tags of 60 characters. An assistant can follow a tag to use every resource carrying it.", "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "source": { "description": "Where this resource comes from, shown with every citation of it: a URL or a mention such as \"Employee handbook, 2026 edition\". Up to 500 characters; an empty string clears it.", "type": "string", "maxLength": 500 } }, "required": [ "type", "url" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "site" }, "url": { "type": "string", "minLength": 4, "maxLength": 2000, "description": "The site, a section of it, or its sitemap. Preview it first with POST /v1/sites/preview." }, "title": { "description": "Defaults to the site's host name.", "type": "string", "minLength": 1, "maxLength": 200 }, "tags": { "description": "Up to 30 tags of 60 characters. An assistant can follow a tag to use every resource carrying it.", "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "source": { "description": "Where this resource comes from, shown with every citation of it: a URL or a mention such as \"Employee handbook, 2026 edition\". Up to 500 characters; an empty string clears it.", "type": "string", "maxLength": 500 }, "rules": { "default": { "include": [], "exclude": [], "excluded_urls": [] }, "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } } }, "schedule": { "description": "Omit to use the plan default: `manual` on Free, `weekly` on paid plans. Recurring schedules require a paid plan.", "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$" } }, "required": [ "type", "url" ] } ] }, "examples": { "text": { "summary": "A text", "value": { "type": "text", "title": "Refund policy", "text": "# Refunds\n\nItems can be returned within 30 days of delivery.", "tags": [ "legal", "faq" ] } }, "page": { "summary": "A web page", "value": { "type": "url", "url": "https://example.com/pricing", "tags": [ "pricing" ] } }, "site": { "summary": "A whole site, only its docs", "value": { "type": "site", "url": "https://example.com", "rules": { "include": [ "/docs/**" ], "exclude": [ "/docs/archive/**" ] }, "schedule": "weekly" } } } } } } } }, "/v1/resources/file": { "post": { "operationId": "uploadFile", "x-surface-coverage": { "cli": "lookio resources add-file", "mcp": null, "mcpReason": "A file is bytes the model does not hold: an MCP tool argument would carry it as base64 inside the model's context, which is slow, costly and capped. Agents upload through the CLI or the REST route.", "cliInputs": { "file_name": { "inputs": [ "arg:path" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Add a file", "description": "Send the file's bytes as the request body and its name in `file_name`. The body is the file itself, not multipart: it is streamed to storage without being held in memory, so `Content-Length` is required. Any `Content-Type` is accepted; the extension of `file_name` decides how the file is read. Reads PDF, Word, PowerPoint, Excel, OpenDocument, CSV, Markdown, HTML, text and images (scans and photos through OCR), up to 50 MB depending on the format (`GET /v1/account` lists the formats and their limits); a format Lookio does not read (.doc, .ppt, .odp, .rtf, .pages, .key, .epub, .zip, .heic) is refused with what to convert it to. By default the resource comes back `queued` and is read and indexed in the background (seconds for a short text, file or page, minutes for a site). Pass `?wait=true` to wait up to 15 seconds for it to finish in one call, or poll `GET /v1/resources/{id}` (`?wait=true` works there too) until `status` is `ready` or `failed`. Importing costs no credits.", "tags": [ "resources" ], "parameters": [ { "name": "file_name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The file's name with its extension, which decides how it is read (PDF, Word, Excel, CSV, images, Markdown, HTML…)." } }, { "name": "title", "in": "query", "required": false, "schema": { "description": "Defaults to the file name without its extension.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "tags", "in": "query", "required": false, "schema": { "description": "Comma-separated tags.", "type": "string", "maxLength": 2000 } }, { "name": "source", "in": "query", "required": false, "schema": { "description": "Where this resource comes from, shown with every citation of it: a URL or a mention such as \"Employee handbook, 2026 edition\". Up to 500 characters; an empty string clears it.", "type": "string", "maxLength": 500 } }, { "name": "wait", "in": "query", "required": false, "schema": { "description": "Wait up to 15 seconds for reading and indexing to finish before returning. Short texts, files and pages usually come back `ready` (or `failed`) in one call; larger imports return their current status (`queued` or `processing`) when the window ends, never an error.", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "resources:write" ] } ], "responses": { "201": { "description": "Add a file", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "file", "url", "site" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed", "stale", "ready_simulated" ], "description": "`queued` and `processing`: being read and indexed (pass `wait=true` or poll until it changes). `ready`: searchable. `failed`: see `status_detail`, then fix and call reindex." }, "status_detail": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source_url": { "description": "The page or site address, for `url` and `site` resources.", "type": [ "string", "null" ] }, "source": { "description": "Where it comes from, as shown with its citations.", "type": [ "string", "null" ] }, "site": { "anyOf": [ { "type": "object", "properties": { "rules": { "default": { "include": [], "exclude": [], "excluded_urls": [] }, "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } }, "required": [ "include", "exclude", "excluded_urls" ], "additionalProperties": false }, "schedule": { "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$", "description": "`manual` syncs only on request. Recurring schedules accept `daily`, `weekly`, `monthly`, or `every_N_days`, `every_N_weeks` and `every_N_months` (1-90 days, 1-52 weeks, 1-12 months). Recurring schedules require a paid plan." }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "rules", "schedule", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "A site's page rules and schedule; null for other types." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "type", "status", "status_detail", "tags", "source_url", "source", "site", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "res_thk6smb5nvts", "title": "Handbook", "type": "file", "status": "queued", "status_detail": null, "tags": [ "hr" ], "source_url": null, "source": "Employee handbook, 2026 edition", "site": null, "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "invalid_parameter", "request_too_large", "conflict", "request_too_large_for_plan", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "description": "The file's bytes, unencoded. `Content-Length` is required.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } } } }, "/v1/resources/{resource_id}": { "get": { "operationId": "getResource", "x-surface-coverage": { "cli": "lookio resources get", "mcp": "get_resource" }, "summary": "Retrieve a resource", "description": "One resource and its import status. Pass `wait=true` to wait up to 15 seconds while status is `queued` or `processing`. A deleted resource or one from another workspace answers the same 404 `resource_not_found` as one that never existed.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "wait", "in": "query", "required": false, "schema": { "description": "Wait up to 15 seconds for reading and indexing to finish before returning. Short texts, files and pages usually come back `ready` (or `failed`) in one call; larger imports return their current status (`queued` or `processing`) when the window ends, never an error.", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "0", "1", "true", "false" ] } ] } } ], "security": [ { "bearerAuth": [ "resources:read" ] } ], "responses": { "200": { "description": "Retrieve a resource", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "file", "url", "site" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed", "stale", "ready_simulated" ], "description": "`queued` and `processing`: being read and indexed (pass `wait=true` or poll until it changes). `ready`: searchable. `failed`: see `status_detail`, then fix and call reindex." }, "status_detail": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source_url": { "description": "The page or site address, for `url` and `site` resources.", "type": [ "string", "null" ] }, "source": { "description": "Where it comes from, as shown with its citations.", "type": [ "string", "null" ] }, "site": { "anyOf": [ { "type": "object", "properties": { "rules": { "default": { "include": [], "exclude": [], "excluded_urls": [] }, "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } }, "required": [ "include", "exclude", "excluded_urls" ], "additionalProperties": false }, "schedule": { "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$", "description": "`manual` syncs only on request. Recurring schedules accept `daily`, `weekly`, `monthly`, or `every_N_days`, `every_N_weeks` and `every_N_months` (1-90 days, 1-52 weeks, 1-12 months). Recurring schedules require a paid plan." }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "rules", "schedule", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "A site's page rules and schedule; null for other types." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "type", "status", "status_detail", "tags", "source_url", "source", "site", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "res_thk6smb5nvts", "title": "Refund policy", "type": "text", "status": "ready", "status_detail": null, "tags": [ "legal", "faq" ], "source_url": null, "source": "Employee handbook, 2026 edition", "site": null, "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "resource_not_found", "rate_limited", "internal_error" ] }, "patch": { "operationId": "updateResource", "x-surface-coverage": { "cli": "lookio resources update", "mcp": "update_resource" }, "summary": "Update a resource", "description": "Changes its title, its tags, or, for a text resource, its text. A new text, or a new title on a file, is re-indexed; the resource stays searchable on its current version meanwhile.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "resources:write" ] } ], "responses": { "200": { "description": "Update a resource", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "file", "url", "site" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed", "stale", "ready_simulated" ], "description": "`queued` and `processing`: being read and indexed (pass `wait=true` or poll until it changes). `ready`: searchable. `failed`: see `status_detail`, then fix and call reindex." }, "status_detail": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source_url": { "description": "The page or site address, for `url` and `site` resources.", "type": [ "string", "null" ] }, "source": { "description": "Where it comes from, as shown with its citations.", "type": [ "string", "null" ] }, "site": { "anyOf": [ { "type": "object", "properties": { "rules": { "default": { "include": [], "exclude": [], "excluded_urls": [] }, "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } }, "required": [ "include", "exclude", "excluded_urls" ], "additionalProperties": false }, "schedule": { "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$", "description": "`manual` syncs only on request. Recurring schedules accept `daily`, `weekly`, `monthly`, or `every_N_days`, `every_N_weeks` and `every_N_months` (1-90 days, 1-52 weeks, 1-12 months). Recurring schedules require a paid plan." }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "rules", "schedule", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "A site's page rules and schedule; null for other types." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "type", "status", "status_detail", "tags", "source_url", "source", "site", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "res_thk6smb5nvts", "title": "Refund policy", "type": "text", "status": "ready", "status_detail": null, "tags": [ "legal", "faq" ], "source_url": null, "source": "Employee handbook, 2026 edition", "site": null, "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "request_too_large_for_plan", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "tags": { "description": "Up to 30 tags of 60 characters. An assistant can follow a tag to use every resource carrying it.", "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "text": { "description": "Text resources only: the new text, which is re-indexed.", "type": "string", "minLength": 1, "maxLength": 100000 }, "source": { "description": "Where this resource comes from, shown with every citation of it: a URL or a mention such as \"Employee handbook, 2026 edition\". Up to 500 characters; an empty string clears it.", "type": "string", "maxLength": 500 } } }, "examples": { "tags": { "summary": "Replace the tags", "value": { "tags": [ "legal" ] } } } } } } }, "delete": { "operationId": "deleteResource", "x-surface-coverage": { "cli": "lookio resources delete", "mcp": "delete_resource" }, "summary": "Delete a resource", "description": "Deletes the resource, its files and its indexed passages. Refused with `conflict` while an assistant that reads only chosen resources (`knowledge: selected`) lists it: remove it from the assistant first. An assistant that reads everything, or a tag, simply reads one resource fewer.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "resources:delete" ] } ], "responses": { "200": { "description": "Delete a resource", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "res_thk6smb5nvts", "deleted": true }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "resource_not_found", "conflict", "rate_limited", "internal_error" ] } }, "/v1/resources/{resource_id}/content": { "get": { "operationId": "getResourceContent", "x-surface-coverage": { "cli": "lookio resources content", "mcp": "get_resource_content" }, "summary": "Read what was indexed", "description": "The text of the published version, in Markdown, as the assistants search it, with what reading could not use. Up to 200,000 characters; for a long resource read a window with `offset` and `limit` and continue from `next_offset`.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "offset", "in": "query", "required": false, "schema": { "description": "Where to start, in characters. Default 0. Pass `next_offset` from the previous response to read on.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "schema": { "description": "How many characters to return, at most 200,000. Omit it to read everything from `offset`.", "type": "integer", "minimum": 1, "maximum": 200000 } } ], "security": [ { "bearerAuth": [ "resources:read" ] } ], "responses": { "200": { "description": "Read what was indexed", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "file", "url", "site" ] }, "file_name": { "type": [ "string", "null" ] }, "page_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "passages": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How many passages the published version was cut into." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "What reading could not use, such as pages without readable text." }, "text": { "type": "string", "description": "The text as indexed, in Markdown, from `offset` for at most `limit` characters." }, "truncated": { "type": "boolean", "description": "True when the resource itself is longer than the 200,000 characters Lookio keeps readable. It says nothing about this window: for that, read `has_more` or `next_offset`." }, "has_more": { "type": "boolean", "description": "True when more text follows this window: continue at `next_offset`." }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Where `text` starts, in characters." }, "total_chars": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The length of the readable text (at most 200,000)." }, "next_offset": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Where to continue, or null when `text` reaches the end." } }, "required": [ "title", "type", "file_name", "page_count", "passages", "warnings", "text", "truncated", "has_more", "offset", "total_chars", "next_offset" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "resource_not_found", "rate_limited", "internal_error", "service_unavailable" ] } }, "/v1/resources/{resource_id}/reindex": { "post": { "operationId": "reindexResource", "x-surface-coverage": { "cli": "lookio resources reindex", "mcp": "reindex_resource" }, "summary": "Re-index a resource, or sync a site", "description": "Reads the resource again: a page is fetched again, a file re-read from its stored original, a site synchronised (new pages added, changed ones re-read, pages gone twice removed). Costs no credits.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "resources:write" ] } ], "responses": { "202": { "description": "Re-index a resource, or sync a site", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "already_running": { "type": "boolean", "description": "Sites only: a synchronisation was already in progress, nothing new was started." } }, "required": [ "id", "already_running" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "resource_not_found", "conflict", "request_too_large_for_plan", "rate_limited", "internal_error", "service_unavailable" ] } }, "/v1/resources/{resource_id}/pages": { "get": { "operationId": "listSitePages", "x-surface-coverage": { "cli": "lookio sites pages", "mcp": "list_site_pages" }, "summary": "List a site's pages", "description": "The pages of a site resource, sorted by address, with their state and why a page failed when it did. `counts` covers every page of the site; filter with `status` (for instance `failed`) and paginate with `cursor`. Up to 5,000 pages.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "pattern": "^doc_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "description": "Only pages in this state. `busy` is every page being read.", "type": "string", "enum": [ "ready", "busy", "failed" ] } } ], "security": [ { "bearerAuth": [ "resources:read" ] } ], "responses": { "200": { "description": "List a site's pages", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] }, "counts": { "type": "object", "properties": { "ready": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "busy": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "ready", "busy", "failed" ], "additionalProperties": false, "description": "Over every page of the site, whatever the filter." }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^doc_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "url": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "detail": { "description": "Why a page could not be read, when it failed.", "type": [ "string", "null" ] }, "missing": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Consecutive syncs where the page was absent. A page absent twice is removed." }, "updated_at": { "type": "string" } }, "required": [ "id", "url", "title", "status", "detail", "missing", "updated_at" ], "additionalProperties": false }, "description": "One page of the site's pages, sorted by address." }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "url", "last_synced_at", "counts", "pages", "has_more", "next_cursor" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "invalid_cursor", "resource_not_found", "conflict", "rate_limited", "internal_error" ] } }, "/v1/resources/{resource_id}/rules": { "put": { "operationId": "updateSiteRules", "x-surface-coverage": { "cli": "lookio sites rules", "mcp": "update_site_rules", "cliInputs": { "rules": { "inputs": [ "--include", "--exclude", "--exclude-url", "--regex" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Change which pages of a site are imported", "description": "Replaces all of a site's rules (the patterns go inside `rules`; omit it to keep the current ones) and, when provided, its schedule, then synchronises it: pages the new rules leave out are removed, new ones imported.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "resources:write" ] } ], "responses": { "200": { "description": "Change which pages of a site are imported", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "title": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "file", "url", "site" ] }, "status": { "type": "string", "enum": [ "queued", "processing", "ready", "failed", "stale", "ready_simulated" ], "description": "`queued` and `processing`: being read and indexed (pass `wait=true` or poll until it changes). `ready`: searchable. `failed`: see `status_detail`, then fix and call reindex." }, "status_detail": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "source_url": { "description": "The page or site address, for `url` and `site` resources.", "type": [ "string", "null" ] }, "source": { "description": "Where it comes from, as shown with its citations.", "type": [ "string", "null" ] }, "site": { "anyOf": [ { "type": "object", "properties": { "rules": { "default": { "include": [], "exclude": [], "excluded_urls": [] }, "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } }, "required": [ "include", "exclude", "excluded_urls" ], "additionalProperties": false }, "schedule": { "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$", "description": "`manual` syncs only on request. Recurring schedules accept `daily`, `weekly`, `monthly`, or `every_N_days`, `every_N_weeks` and `every_N_months` (1-90 days, 1-52 weeks, 1-12 months). Recurring schedules require a paid plan." }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "rules", "schedule", "last_synced_at" ], "additionalProperties": false }, { "type": "null" } ], "description": "A site's page rules and schedule; null for other types." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "title", "type", "status", "status_detail", "tags", "source_url", "source", "site", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "rules": { "description": "The complete new rules, which replace the old ones. Omit to keep the current rules, for example to change only the schedule. Send `{}` to import the whole site.", "type": "object", "properties": { "include": { "default": [], "description": "Path patterns to keep, such as `/docs/**`. `*` is one level, `**` everything below. Empty keeps the whole site.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "exclude": { "default": [], "description": "Path patterns to leave out, such as `/blog/**`.", "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 300 } }, "regex": { "description": "Advanced: a regular expression on the path; matching pages are left out.", "type": "string", "maxLength": 500 }, "excluded_urls": { "default": [], "description": "Single pages to leave out, by full address.", "maxItems": 5000, "type": "array", "items": { "type": "string", "maxLength": 2000 } } } }, "schedule": { "description": "Omit to keep the site's current schedule. Recurring schedules require a paid plan.", "type": "string", "maxLength": 40, "pattern": "^(?:manual|daily|weekly|monthly|every_\\d+_(?:day|days|week|weeks|month|months))$" } } } } } } } }, "/v1/resources/{resource_id}/retry": { "post": { "operationId": "retryFailedPages", "x-surface-coverage": { "cli": "lookio sites retry", "mcp": "retry_failed_pages" }, "summary": "Retry a site's failed pages", "description": "Reads again every page of the site that failed, without a full synchronisation. Costs no credits.", "tags": [ "resources" ], "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "resources:write" ] } ], "responses": { "202": { "description": "Retry a site's failed pages", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "retried": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "retried" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "resource_not_found", "conflict", "rate_limited", "internal_error", "service_unavailable" ] } }, "/v1/sites/preview": { "post": { "operationId": "previewSite", "x-surface-coverage": { "cli": "lookio sites preview", "mcp": "preview_site" }, "summary": "Preview a site before importing it", "description": "Finds a site's pages (its sitemaps, else its links) without creating anything, so you can try rules on `urls` before POST /v1/resources with `type: \"site\"`. Pages forbidden by robots.txt are left out.", "tags": [ "sites" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "resources:write" ] } ], "responses": { "200": { "description": "Preview a site before importing it", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string" }, "source": { "type": "string", "enum": [ "sitemap", "links" ], "description": "`sitemap` when the site publishes one, else `links`: pages found by following links." }, "sitemaps": { "type": "array", "items": { "type": "string" } }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncated": { "type": "boolean", "description": "True when the 10,000-page limit was reached: narrow the rules." }, "disallowed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Pages the site's robots.txt forbids, left out." }, "urls": { "type": "array", "items": { "type": "string" }, "description": "The first pages found, to try rules against." } }, "required": [ "url", "source", "sitemaps", "total", "truncated", "disallowed", "urls" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "conflict", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "minLength": 4, "maxLength": 2000, "description": "The site, a section such as https://docs.acme.com/guide, or its sitemap." } }, "required": [ "url" ] } } } } } }, "/v1/assistants": { "get": { "operationId": "listAssistants", "x-surface-coverage": { "cli": "lookio assistants list", "mcp": "list_assistants" }, "summary": "List assistants", "description": "The assistants this caller may use, newest first.", "tags": [ "assistants" ], "parameters": [], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "List assistants", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "context": { "type": "string" }, "output_guidelines": { "type": "string" }, "resource_ids": { "type": "array", "items": { "type": "string" }, "description": "Empty when this caller may not see the resource catalogue." }, "follow_tags": { "type": "array", "items": { "type": "string" } }, "knowledge": { "type": "string", "enum": [ "all", "selected", "tags" ], "description": "What the assistant reads: `all` is every resource of the workspace, now and later; `selected` is only `resource_ids`; `tags` is every resource carrying a tag in `follow_tags`, now or later. One mode at a time; the lists of the other modes are kept." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "context", "output_guidelines", "resource_ids", "follow_tags", "knowledge", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ] }, "examples": { "default": { "value": { "data": [ { "id": "ast_66xcnwtzj8vt", "name": "Support", "context": "You are the support assistant of Acme. You answer customers who want a quick, accurate reply.", "output_guidelines": "Short answers, in the language of the question.", "resource_ids": [ "res_thk6smb5nvts" ], "follow_tags": [], "knowledge": "selected", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "rate_limited", "internal_error" ] }, "post": { "operationId": "createAssistant", "x-surface-coverage": { "cli": "lookio assistants create", "mcp": "create_assistant", "cliInputs": { "resource_ids": { "inputs": [ "--resources" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Create an assistant", "description": "Creates an assistant. Its `knowledge` mode chooses what it reads, one mode at a time: every workspace resource (`all`), chosen `resource_ids` (`selected`), or every resource carrying one of `follow_tags` (`tags`).", "tags": [ "assistants" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "201": { "description": "Create an assistant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "context": { "type": "string" }, "output_guidelines": { "type": "string" }, "resource_ids": { "type": "array", "items": { "type": "string" }, "description": "Empty when this caller may not see the resource catalogue." }, "follow_tags": { "type": "array", "items": { "type": "string" } }, "knowledge": { "type": "string", "enum": [ "all", "selected", "tags" ], "description": "What the assistant reads: `all` is every resource of the workspace, now and later; `selected` is only `resource_ids`; `tags` is every resource carrying a tag in `follow_tags`, now or later. One mode at a time; the lists of the other modes are kept." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "context", "output_guidelines", "resource_ids", "follow_tags", "knowledge", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "ast_66xcnwtzj8vt", "name": "Support", "context": "You are the support assistant of Acme. You answer customers who want a quick, accurate reply.", "output_guidelines": "Short answers, in the language of the question.", "resource_ids": [ "res_thk6smb5nvts" ], "follow_tags": [], "knowledge": "selected", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "context": { "default": "", "type": "string", "maxLength": 12000, "description": "What the assistant is and who it talks to: its role and its audience." }, "output_guidelines": { "default": "", "type": "string", "maxLength": 12000, "description": "How answers are written: length, format, language." }, "resource_ids": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "description": "The resources it answers from." }, "follow_tags": { "description": "Tags it follows when `knowledge` is `tags`: every resource carrying one, now or later, is used (one `knowledge` mode applies at a time).", "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "knowledge": { "description": "Omit to infer it: `tags` when only tags are given, otherwise `selected`. Send `all` to read every resource.", "type": "string", "enum": [ "all", "selected", "tags" ] } }, "required": [ "name" ] }, "examples": { "selected": { "summary": "Answers from chosen resources", "value": { "name": "Support", "context": "You are the support assistant of Acme, talking to customers.", "resource_ids": [ "res_thk6smb5nvts" ] } }, "tags": { "summary": "Follows a tag", "value": { "name": "Pricing bot", "follow_tags": [ "pricing" ], "knowledge": "tags" } } } } } } } }, "/v1/assistants/{assistant_id}": { "get": { "operationId": "getAssistant", "x-surface-coverage": { "cli": "lookio assistants get", "mcp": "get_assistant" }, "summary": "Retrieve an assistant", "description": "One assistant and its settings. A deleted assistant, an unshared assistant from another workspace, and an unknown id all answer the same 404 `resource_not_found` so ids cannot be enumerated.", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "Retrieve an assistant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "context": { "type": "string" }, "output_guidelines": { "type": "string" }, "resource_ids": { "type": "array", "items": { "type": "string" }, "description": "Empty when this caller may not see the resource catalogue." }, "follow_tags": { "type": "array", "items": { "type": "string" } }, "knowledge": { "type": "string", "enum": [ "all", "selected", "tags" ], "description": "What the assistant reads: `all` is every resource of the workspace, now and later; `selected` is only `resource_ids`; `tags` is every resource carrying a tag in `follow_tags`, now or later. One mode at a time; the lists of the other modes are kept." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "context", "output_guidelines", "resource_ids", "follow_tags", "knowledge", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "ast_66xcnwtzj8vt", "name": "Support", "context": "You are the support assistant of Acme. You answer customers who want a quick, accurate reply.", "output_guidelines": "Short answers, in the language of the question.", "resource_ids": [ "res_thk6smb5nvts" ], "follow_tags": [], "knowledge": "selected", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "resource_not_found", "rate_limited", "internal_error" ] }, "patch": { "operationId": "updateAssistant", "x-surface-coverage": { "cli": "lookio assistants update", "mcp": "update_assistant", "cliInputs": { "resource_ids": { "inputs": [ "--resources" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Update an assistant", "description": "Changes the fields you send and keeps the others.", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "Update an assistant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "context": { "type": "string" }, "output_guidelines": { "type": "string" }, "resource_ids": { "type": "array", "items": { "type": "string" }, "description": "Empty when this caller may not see the resource catalogue." }, "follow_tags": { "type": "array", "items": { "type": "string" } }, "knowledge": { "type": "string", "enum": [ "all", "selected", "tags" ], "description": "What the assistant reads: `all` is every resource of the workspace, now and later; `selected` is only `resource_ids`; `tags` is every resource carrying a tag in `follow_tags`, now or later. One mode at a time; the lists of the other modes are kept." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "context", "output_guidelines", "resource_ids", "follow_tags", "knowledge", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "ast_66xcnwtzj8vt", "name": "Support", "context": "You are the support assistant of Acme. You answer customers who want a quick, accurate reply.", "output_guidelines": "Short answers, in the language of the question.", "resource_ids": [ "res_thk6smb5nvts" ], "follow_tags": [], "knowledge": "selected", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "context": { "type": "string", "maxLength": 12000, "description": "What the assistant is and who it talks to: its role and its audience." }, "output_guidelines": { "type": "string", "maxLength": 12000, "description": "How answers are written: length, format, language." }, "resource_ids": { "maxItems": 200, "type": "array", "items": { "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "description": "The resources it answers from." }, "follow_tags": { "description": "Tags it follows when `knowledge` is `tags`: every resource carrying one, now or later, is used (one `knowledge` mode applies at a time).", "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "knowledge": { "type": "string", "enum": [ "all", "selected", "tags" ], "description": "What the assistant reads: `all` is every resource of the workspace, now and later; `selected` is only `resource_ids`; `tags` is every resource carrying a tag in `follow_tags`, now or later. One mode at a time; the lists of the other modes are kept." } } }, "examples": { "context": { "summary": "New context", "value": { "context": "You are the help center assistant of Acme, talking to French-speaking customers." } } } } } } }, "delete": { "operationId": "deleteAssistant", "x-surface-coverage": { "cli": "lookio assistants delete", "mcp": "delete_assistant" }, "summary": "Delete an assistant", "description": "Deletes the assistant. Its resources are kept; the conversations people had with it stay readable. Refused with `conflict` while a widget uses it: remove the widget first.", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:delete" ] } ], "responses": { "200": { "description": "Delete an assistant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "ast_66xcnwtzj8vt", "deleted": true }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "resource_not_found", "conflict", "rate_limited", "internal_error" ] } }, "/v1/assistants/{assistant_id}/query": { "post": { "operationId": "queryAssistant", "x-surface-coverage": { "cli": "lookio ask", "mcp": "ask_assistant", "mcpInputs": { "stream": { "fields": [], "reason": "Native MCP returns one structured answer. HTTP SSE is a REST transport option, not an additional answer capability." } }, "cliInputs": { "conversation_id": { "inputs": [ "--conversation" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "history": { "inputs": [ "--history-file" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "store": { "inputs": [ "--no-store" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Ask an assistant a question", "description": "Answers from the assistant's resources, with the passages it relies on. The assistant is one of yours, or a public assistant from `GET /v1/public-assistants` (paid by your workspace too, its citations without `resource_id`). Costs Eco 10, Flash 30 credits (the default), Deep 80 per question, depending on `mode` and whatever the answer's length, even when the resources hold no answer or the message is a greeting; an assistant that reads no resource is refused with the error `assistant_has_no_resources` (409), before any credit is held. The modes: Eco (10 credits) searches like Flash on a cheaper tier that may wait a few seconds, and computes exact totals, averages, counts and filters over every row of the tables in the resources (CSV, spreadsheets, tables in documents), saying how many values are missing; it also counts a phrase given in quotes across every document. Flash (30 credits, the default) answers quickly from the most relevant passages of the resources; it computes nothing over tables. Deep (80 credits) searches the question first, splits it into sub-questions in the documents' own terms, searches each part, reranks the evidence, computes exact figures over tables like Eco, and answers with a stronger model. The answer is filed in a conversation: the response carries its `conversation_id` and the answer's `message_id`, and a follow-up sends only the new question with that `conversation_id`, Lookio reads the history itself. A person continues their own chats; an API key continues the conversations it started. An API key can also send `end_user` (its own id for the person asking), which keeps each user's conversations apart and is required again to continue them, and `store: false` to keep nothing (then bring the previous turns yourself as `history`). Kept conversations are readable in the workspace's logs for as long as the plan keeps them readable (7 days on Free, 90 on Starter, 1 year on Pro, from the last message), then deleted some time later. By default the full answer comes back as JSON. With `stream: true` it comes as server-sent events (`text/event-stream`): `status` {phase}, `delta` {text} for each piece of the answer, then `done` with the same fields as the JSON answer (`conversation_id` and `message_id` included), or `error` with the standard error envelope. A stream that fails before its first event is an ordinary JSON error. Send an `Idempotency-Key` header so a retried JSON request is not charged twice (it does not apply to a stream: do not retry one blindly).", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "query" ] } ], "responses": { "200": { "description": "Ask an assistant a question", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "answer": { "type": "string", "description": "Markdown. Citations appear as [1], [2]…" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "The cited resource. Empty for a public assistant of another workspace: its resources stay its own." }, "title": { "type": "string" }, "text": { "type": "string", "description": "The passage the answer relies on." }, "n": { "description": "The number the answer cites it by, as [1].", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "section": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "source": { "description": "The cited resource's source, when it has one.", "type": "string" } }, "required": [ "resource_id", "title", "text" ], "additionalProperties": false } }, "conversation_id": { "description": "The conversation this answer belongs to: pass it back as `conversation_id` to continue it. Null when nothing was stored (`store: false`).", "type": [ "string", "null" ] }, "message_id": { "description": "The id of this answer in the conversation. On an API key's conversation it is what `POST /v1/conversations/{conversation_id}/messages/{message_id}/feedback` takes (a person's own chats take no thumbs yet). Null when nothing was stored.", "type": [ "string", "null" ] }, "credit_cost": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this answer cost. A model answer costs its mode's fixed price." }, "credits_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "simulated": { "type": "boolean", "description": "True on a development deployment answering without a model." } }, "required": [ "answer", "citations", "conversation_id", "message_id", "credit_cost", "credits_remaining", "simulated" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "answer": "You can return an item within 30 days of delivery [1].", "citations": [ { "resource_id": "res_thk6smb5nvts", "title": "Refund policy", "text": "Items can be returned within 30 days of delivery, unused and in their original packaging.", "n": 1, "section": [ "Refunds", "Window" ], "source": "Employee handbook, 2026 edition" } ], "conversation_id": "cnv_ca9xz837zsvb", "message_id": "msg_6ec9htp67dd7", "credit_cost": 30, "credits_remaining": 9970, "simulated": false }, "request_id": "req_01K9X7M2Q4" } } } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events, sent when the request body has `stream: true`. Each event is `event: ` then `data: `. Events arrive in this order: zero or more `status`, then `delta` for each piece of the answer, then exactly one `done` (the full answer, shaped like the JSON response) or one `error` (the standard error envelope; the stream ends after it). Lines starting with `:` are keep-alive comments, sent every 15 seconds while the answer is not ready: ignore them. A stream that ends without `done` or `error` was cut off. The charge is settled when `done` is sent; a client that leaves early does not cancel the answer.", "x-event-schemas": { "status": { "$ref": "#/components/schemas/StreamStatusEvent" }, "delta": { "$ref": "#/components/schemas/StreamDeltaEvent" }, "done": { "$ref": "#/components/schemas/StreamDoneEvent" }, "error": { "$ref": "#/components/schemas/StreamErrorEvent" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "assistant_has_no_resources", "insufficient_credits", "rate_limited", "internal_error", "service_unavailable" ], "x-sse-events": [ "status", "delta", "done", "error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 12000 }, "conversation_id": { "description": "Continue a conversation from an earlier answer's `conversation_id`: Lookio reads its history itself, so send only the new question. A person continues their own chats; an API key continues the conversations it started (and, when you send `end_user`, only that person's). A conversation stays with the assistant that started it. Not with `history` and not with `store: false`.", "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "history": { "description": "The previous turns, oldest first; the last 6 are used, and they are not stored as such. For a conversation you keep yourself. Without `conversation_id`, an API key's answer starts a new conversation in Lookio's logs unless `store` is false.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string", "maxLength": 12000 } }, "required": [ "role", "content" ] } }, "end_user": { "description": "API keys only. Your own id for the person asking (a user id of your product): 1 to 200 characters, letters, digits and `. _ @ : + -`. Prefer an opaque id: it shows in the workspace's logs. It groups that person's conversations, and a conversation can then only be continued with the same `end_user`.", "type": "string", "pattern": "^[\\w.@:+\\-]{1,200}$" }, "store": { "description": "API keys only. `false` keeps nothing: no conversation, no log, `conversation_id` and `message_id` come back null, and the answer cannot be continued except with `history`. Default `true`: the exchange is kept, continues with `conversation_id` and is readable in the workspace's logs for as long as the plan keeps conversations readable (7 days on Free, 90 on Starter, 1 year on Pro). Not with `conversation_id`.", "type": "boolean" }, "mode": { "default": "flash", "description": "Eco 10, Flash 30 credits (the default), Deep 80. flash is the default; eco may take longer to start, deep splits the question and answers with a stronger model. One price per answer, whatever its length. Every question the assistant works on is charged, even when its resources hold no answer or the message is a greeting; an assistant that reads no resource is refused with the error assistant_has_no_resources, before any credit is held.", "type": "string", "enum": [ "eco", "flash", "deep" ] }, "stream": { "default": false, "description": "`true` returns server-sent events (`text/event-stream`): `status` (searching, reading, answering), `delta` with each piece of the answer, then `done` with the full answer, or `error` with the standard error envelope. Comment lines (`: keep-alive`) arrive every 15 seconds while waiting. Idempotency-Key does not apply to a stream.", "type": "boolean" } }, "required": [ "question" ] }, "examples": { "simple": { "summary": "A question", "value": { "question": "What is the refund window?" } }, "endUser": { "summary": "An API key asking for one of its users", "value": { "question": "What is the refund window?", "end_user": "user_42" } }, "followUp": { "summary": "A follow-up: only the new question and the conversation_id of the previous answer", "value": { "question": "And for gift cards?", "conversation_id": "cnv_ca9xz837zsvb", "end_user": "user_42" } }, "noStore": { "summary": "An API key keeping nothing, with its own history", "value": { "question": "And for gift cards?", "store": false, "history": [ { "role": "user", "content": "What is the refund window?" }, { "role": "assistant", "content": "You can return an item within 30 days of delivery [1]." } ], "mode": "eco" } }, "stream": { "summary": "Streamed", "value": { "question": "Summarise the refund policy", "stream": true } } } } } } } }, "/v1/conversations": { "get": { "operationId": "listConversations", "x-surface-coverage": { "cli": "lookio conversations list", "mcp": "list_conversations", "cliInputs": { "assistant_id": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "List your conversations", "description": "The caller's own conversations, latest activity first, optionally with one assistant (`assistant_id`). For a person: their chats, personal, nobody else's is listed, admins included. For an API key: the conversations its questions started, optionally of one `end_user`. `channel` says which it is. A conversation whose assistant was deleted stays listed with `assistant_deleted: true`. This is not the workspace's view of what people asked: that is `GET /v1/logs/conversations`.", "tags": [ "conversations" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Only the conversations with this assistant.", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "end_user", "in": "query", "required": false, "schema": { "description": "API keys only: only the conversations of this `end_user`, the id you sent with the questions.", "type": "string", "pattern": "^[\\w.@:+\\-]{1,200}$" } } ], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "List your conversations", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "assistant_id": { "type": "string" }, "assistant_deleted": { "type": "boolean", "description": "True when the assistant was deleted since: the conversation stays readable but cannot be continued." }, "title": { "type": "string", "description": "Defaults to the first 100 characters of the opening question until renamed (`PATCH /v1/conversations/{conversation_id}`, up to 100 characters)." }, "channel": { "type": "string", "enum": [ "personal", "api", "mcp" ], "description": "`personal`: a person's own chat (the app, or their connection). `api`: an API key's conversation (REST, CLI, SDK). `mcp`: an API key's conversation through the MCP server." }, "end_user": { "description": "The `end_user` sent with the questions of an API key's conversation. Null for a personal chat and when none was sent.", "type": [ "string", "null" ] }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Questions and answers together." }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "description": "The last activity. Conversations are listed by it, latest first." } }, "required": [ "id", "assistant_id", "assistant_deleted", "title", "channel", "end_user", "message_count", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] }, "examples": { "default": { "value": { "data": [ { "id": "cnv_ca9xz837zsvb", "assistant_id": "ast_66xcnwtzj8vt", "assistant_deleted": false, "title": "What is the refund window?", "channel": "api", "end_user": "user_42", "message_count": 4, "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "invalid_parameter", "invalid_cursor", "rate_limited", "internal_error" ] } }, "/v1/conversations/{conversation_id}": { "get": { "operationId": "getConversation", "x-surface-coverage": { "cli": "lookio conversations get", "mcp": "get_conversation" }, "summary": "Retrieve a conversation", "description": "One of the caller's conversations with its messages and citations, and each message's `id` (an answer's id is what the feedback endpoint takes) and thumb. A person's chats are personal: someone else's answers 404, admins included. An API key reads the conversations it started, and with `end_user` only that person's. `assistant_deleted` is true when the assistant is gone: the conversation stays readable but cannot be continued.", "tags": [ "conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "end_user", "in": "query", "required": false, "schema": { "description": "API keys only: the `end_user` of the conversation. When given, a conversation of another end user answers not found.", "type": "string", "pattern": "^[\\w.@:+\\-]{1,200}$" } } ], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "Retrieve a conversation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "assistant_id": { "type": "string" }, "assistant_deleted": { "type": "boolean", "description": "True when the assistant was deleted since: the conversation stays readable but cannot be continued." }, "title": { "type": "string", "description": "Defaults to the first 100 characters of the opening question until renamed (`PATCH /v1/conversations/{conversation_id}`, up to 100 characters)." }, "channel": { "type": "string", "enum": [ "personal", "api", "mcp" ], "description": "`personal`: a person's own chat (the app, or their connection). `api`: an API key's conversation (REST, CLI, SDK). `mcp`: an API key's conversation through the MCP server." }, "end_user": { "description": "The `end_user` sent with the questions of an API key's conversation. Null for a personal chat and when none was sent.", "type": [ "string", "null" ] }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Questions and answers together." }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "description": "The last activity. Conversations are listed by it, latest first." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The message's id. An answer's id is what the feedback endpoint takes." }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "The cited resource. Empty for a public assistant of another workspace: its resources stay its own." }, "title": { "type": "string" }, "text": { "type": "string", "description": "The passage the answer relies on." }, "n": { "description": "The number the answer cites it by, as [1].", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "section": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "source": { "description": "The cited resource's source, when it has one.", "type": "string" } }, "required": [ "resource_id", "title", "text" ], "additionalProperties": false } }, "rating": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ], "description": "The thumb sent for this answer. Always null in a personal chat (no thumbs there yet)." }, "rating_comment": { "description": "The comment sent with the thumb.", "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "role", "content", "citations", "rating", "rating_comment", "created_at" ], "additionalProperties": false } } }, "required": [ "id", "assistant_id", "assistant_deleted", "title", "channel", "end_user", "message_count", "created_at", "updated_at", "messages" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "invalid_parameter", "resource_not_found", "rate_limited", "internal_error" ] }, "patch": { "operationId": "renameConversation", "x-surface-coverage": { "cli": "lookio conversations rename", "mcp": "rename_conversation" }, "summary": "Rename a conversation", "description": "Changes the title of one of the caller's conversations (a person's chat, or a conversation of the API key). The new title shows in the workspace's logs too.", "tags": [ "conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "query" ] } ], "responses": { "200": { "description": "Rename a conversation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "cnv_ca9xz837zsvb", "title": "Refund questions" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The new title, 1 to 100 characters." }, "end_user": { "description": "API keys only: the `end_user` of the conversation. When given, a conversation of another end user answers not found.", "type": "string", "pattern": "^[\\w.@:+\\-]{1,200}$" } }, "required": [ "title" ] }, "examples": { "title": { "summary": "A new title", "value": { "title": "Refund questions" } } } } } } }, "delete": { "operationId": "deleteConversation", "x-surface-coverage": { "cli": "lookio conversations delete", "mcp": "delete_conversation" }, "summary": "Delete a conversation", "description": "Deletes one of the caller's conversations and its messages. Cannot be undone. An API key's conversation disappears from the workspace's logs too, and its thumbs from the figures: nobody can read it afterwards. To honour a user's request to erase their data, delete each of their conversations (list them with `end_user`).", "tags": [ "conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "end_user", "in": "query", "required": false, "schema": { "description": "API keys only: the `end_user` of the conversation. When given, a conversation of another end user answers not found.", "type": "string", "pattern": "^[\\w.@:+\\-]{1,200}$" } } ], "security": [ { "bearerAuth": [ "query" ] } ], "responses": { "200": { "description": "Delete a conversation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "cnv_ca9xz837zsvb", "deleted": true }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "invalid_parameter", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/conversations/{conversation_id}/messages/{message_id}/feedback": { "post": { "operationId": "submitAnswerFeedback", "x-surface-coverage": { "cli": "lookio conversations feedback", "mcp": "send_answer_feedback" }, "summary": "Send feedback on an answer", "description": "Records your user's thumb on one answer of an API key's conversation, with an optional comment, so the workspace sees where the assistant fell short (`GET /v1/logs/conversations?rating=down`). `conversation_id` and `message_id` come from the answer. Sending another thumb replaces the first; `rating: null` takes it back. Costs nothing. API keys only: thumbs on a personal chat are not available yet (`feature_not_available`).", "tags": [ "conversations" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "message_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^msg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "query" ] } ], "responses": { "200": { "description": "Send feedback on an answer", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversation_id": { "type": "string" }, "message_id": { "type": "string" }, "rating": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ] }, "comment": { "type": [ "string", "null" ] } }, "required": [ "conversation_id", "message_id", "rating", "comment" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "conversation_id": "cnv_ca9xz837zsvb", "message_id": "msg_6ec9htp67dd7", "rating": "down", "comment": "The price is out of date." }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "rating": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ], "description": "`up` or `down`: your user's thumb on this answer. `null` takes it back. Sending another thumb replaces the first, it never counts twice." }, "comment": { "description": "What your user wrote with the thumb, up to 1,000 characters. Only with `up` or `down`.", "type": "string", "maxLength": 1000 }, "end_user": { "description": "The `end_user` of the conversation, when you use them. When given, a conversation of another end user answers not found.", "type": "string", "pattern": "^[\\w.@:+\\-]{1,200}$" } }, "required": [ "rating" ] }, "examples": { "down": { "summary": "A thumbs down with a comment", "value": { "rating": "down", "comment": "The price is out of date.", "end_user": "user_42" } }, "undo": { "summary": "Taking a thumb back", "value": { "rating": null } } } } } } } }, "/v1/logs/conversations": { "get": { "operationId": "listLogConversations", "x-surface-coverage": { "cli": "lookio logs conversations", "mcp": "list_conversation_logs", "cliInputs": { "widget_id": { "inputs": [ "--widget" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "api_key_id": { "inputs": [ "--api-key" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "assistant_id": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "q": { "inputs": [ "--query" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "List the workspace's conversation logs", "description": "What people outside the workspace asked, from every channel: visitors of your widgets, and the users of your own product who reach an assistant through an API key (REST, CLI, SDK) or the MCP server. Latest activity first, with who asked (`end_user`), through what (`widget` or `api_key`), how many messages, what it cost and the thumbs. Filter by `channel`, `widget_id`, `api_key_id`, `assistant_id`, `rating` (`down` finds where the assistant failed), `end_user`, `q` (words in any message) and `from`/`to`, and paginate with `cursor`. Read one in full with `GET /v1/logs/conversations/{conversation_id}` and the figures above the list with `GET /v1/logs/conversations/stats`. Members' own chats with assistants are personal and never appear here. A conversation is kept 90 days after its last message. Needs the right to edit assistants; an API key sees the conversations of its own assistants. Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "description": "Only the conversations from these channels, comma-separated: `widget` (visitors of a widget), `api` (an API key through REST, the CLI or the SDK), `mcp` (an API key through the MCP server). Default: all three.", "minLength": 1 } }, { "name": "widget_id", "in": "query", "required": false, "schema": { "description": "Only this widget's visitors.", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "api_key_id", "in": "query", "required": false, "schema": { "description": "Only the conversations asked with this API key (the `api_key.id` of a conversation in these logs).", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Only the conversations with this assistant.", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "rating", "in": "query", "required": false, "schema": { "description": "`down`: at least one thumbs down (where the assistant failed). `up`: at least one thumbs up. `rated`: any thumb. `unrated`: none.", "type": "string", "enum": [ "up", "down", "rated", "unrated" ] } }, { "name": "end_user", "in": "query", "required": false, "schema": { "description": "Only this person: a widget visitor's random id, or the `end_user` your product sends with its questions.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "schema": { "description": "Words in the title or in any question or answer, without regard to case.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "schema": { "description": "Only conversations with activity since this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Only conversations started before this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "List the workspace's conversation logs", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "channel": { "type": "string", "enum": [ "widget", "api", "mcp" ], "description": "`widget`: a visitor on your website. `api`: an API key through REST, the CLI or the SDK. `mcp`: an API key through the MCP server." }, "title": { "type": "string", "description": "The first question." }, "assistant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null when the assistant was deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, "widget": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The widget, for the `widget` channel." }, "api_key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null once the key is deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The API key, for the `api` and `mcp` channels." }, "end_user": { "description": "Who was asking: a widget visitor's random id, or the `end_user` the product sent. Null when an API key sent none.", "type": [ "string", "null" ] }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Questions and answers together." }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What this conversation's answers cost." }, "thumbs_up": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "thumbs_down": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "description": "The last activity. Conversations are listed by it, latest first." }, "locked": { "type": "boolean", "description": "Older than the plan keeps conversations readable (7 days on Free, 90 on Starter, 1 year on Pro, from the last activity). Its text is hidden, not yet deleted: `title` is then a date and `messages` is empty, and a higher plan shows it again." } }, "required": [ "id", "channel", "title", "assistant", "widget", "api_key", "end_user", "message_count", "credits", "thumbs_up", "thumbs_down", "created_at", "updated_at", "locked" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] }, "examples": { "default": { "value": { "data": [ { "id": "cnv_ca9xz837zsvb", "channel": "api", "title": "What is the refund window?", "assistant": { "id": "ast_66xcnwtzj8vt", "name": "Support" }, "widget": null, "api_key": { "id": "k_7f3a9c", "name": "Help centre backend" }, "end_user": "user_42", "message_count": 4, "credits": 60, "thumbs_up": 0, "thumbs_down": 1, "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z", "locked": false } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "rate_limited", "internal_error" ] } }, "/v1/logs/conversations/stats": { "get": { "operationId": "getLogConversationStats", "x-surface-coverage": { "cli": "lookio logs conversations --stats", "mcp": "get_conversation_log_stats", "cliInputs": { "widget_id": { "inputs": [ "--widget" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "api_key_id": { "inputs": [ "--api-key" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "assistant_id": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "q": { "inputs": [ "--query" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Retrieve the figures of the conversation logs", "description": "Conversations, questions, distinct people, credits and thumbs over the same filters as `GET /v1/logs/conversations` (without `cursor` and `limit`), with the conversations per channel. With no filter it covers every log still kept (90 days). Needs the right to edit assistants. Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "description": "Only the conversations from these channels, comma-separated: `widget` (visitors of a widget), `api` (an API key through REST, the CLI or the SDK), `mcp` (an API key through the MCP server). Default: all three.", "minLength": 1 } }, { "name": "widget_id", "in": "query", "required": false, "schema": { "description": "Only this widget's visitors.", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "api_key_id", "in": "query", "required": false, "schema": { "description": "Only the conversations asked with this API key (the `api_key.id` of a conversation in these logs).", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Only the conversations with this assistant.", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "rating", "in": "query", "required": false, "schema": { "description": "`down`: at least one thumbs down (where the assistant failed). `up`: at least one thumbs up. `rated`: any thumb. `unrated`: none.", "type": "string", "enum": [ "up", "down", "rated", "unrated" ] } }, { "name": "end_user", "in": "query", "required": false, "schema": { "description": "Only this person: a widget visitor's random id, or the `end_user` your product sends with its questions.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "q", "in": "query", "required": false, "schema": { "description": "Words in the title or in any question or answer, without regard to case.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "schema": { "description": "Only conversations with activity since this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Only conversations started before this ISO 8601 date or timestamp.", "type": "string" } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "Retrieve the figures of the conversation logs", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "questions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Questions asked, so answers given." }, "people": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Distinct `end_user` values. A conversation without one counts as one person." }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "thumbs_up": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "thumbs_down": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "by_channel": { "type": "object", "properties": { "widget": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "api": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mcp": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "widget", "api", "mcp" ], "additionalProperties": false, "description": "Conversations per channel." } }, "required": [ "conversations", "questions", "people", "credits", "thumbs_up", "thumbs_down", "by_channel" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "conversations": 120, "questions": 310, "people": 64, "credits": 9300, "thumbs_up": 41, "thumbs_down": 7, "by_channel": { "widget": 80, "api": 35, "mcp": 5 } }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "rate_limited", "internal_error" ] } }, "/v1/logs/conversations/{conversation_id}": { "get": { "operationId": "getLogConversation", "x-surface-coverage": { "cli": "lookio logs get", "mcp": "get_conversation_log" }, "summary": "Retrieve a logged conversation", "description": "One conversation in full, whatever its channel: every question and answer with the passages the answer relied on, its query mode, what it cost, how long it took and the thumb with its comment. A personal chat of a member is not here (404). Needs the right to edit assistants. Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "Retrieve a logged conversation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "channel": { "type": "string", "enum": [ "widget", "api", "mcp" ], "description": "`widget`: a visitor on your website. `api`: an API key through REST, the CLI or the SDK. `mcp`: an API key through the MCP server." }, "title": { "type": "string", "description": "The first question." }, "assistant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null when the assistant was deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, "widget": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The widget, for the `widget` channel." }, "api_key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null once the key is deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The API key, for the `api` and `mcp` channels." }, "end_user": { "description": "Who was asking: a widget visitor's random id, or the `end_user` the product sent. Null when an API key sent none.", "type": [ "string", "null" ] }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Questions and answers together." }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What this conversation's answers cost." }, "thumbs_up": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "thumbs_down": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "description": "The last activity. Conversations are listed by it, latest first." }, "locked": { "type": "boolean", "description": "Older than the plan keeps conversations readable (7 days on Free, 90 on Starter, 1 year on Pro, from the last activity). Its text is hidden, not yet deleted: `title` is then a date and `messages` is empty, and a higher plan shows it again." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "The cited resource. Empty for a public assistant of another workspace: its resources stay its own." }, "title": { "type": "string" }, "text": { "type": "string", "description": "The passage the answer relies on." }, "n": { "description": "The number the answer cites it by, as [1].", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "section": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "source": { "description": "The cited resource's source, when it has one.", "type": "string" } }, "required": [ "resource_id", "title", "text" ], "additionalProperties": false }, "description": "The passages the answer relied on." }, "credit_cost": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Answers only: what it cost." }, "mode": { "description": "Answers only: the query mode.", "type": [ "string", "null" ] }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Answers only: how long it took to write." }, "rating": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ], "description": "The thumb on an answer, from the visitor or forwarded by your product." }, "rating_comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "role", "content", "citations", "credit_cost", "mode", "duration_ms", "rating", "rating_comment", "created_at" ], "additionalProperties": false } } }, "required": [ "id", "channel", "title", "assistant", "widget", "api_key", "end_user", "message_count", "credits", "thumbs_up", "thumbs_down", "created_at", "updated_at", "locked", "messages" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/logs/answers": { "get": { "operationId": "listLogAnswers", "x-surface-coverage": { "cli": "lookio logs answers", "mcp": "list_answer_logs", "cliInputs": { "assistant_id": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "widget_id": { "inputs": [ "--widget" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "api_key_id": { "inputs": [ "--api-key" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "member_id": { "inputs": [ "--member" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "List the answer logs", "description": "Every answer Lookio produced, one line each, whatever asked: a member in the chat, Lookio AI, an API key (REST, CLI, SDK), the MCP server, a widget's visitor. Latest first, with the assistant, who asked, the query mode, what it cost, how long it took, and the conversation it belongs to when it was kept. No question or answer text: read the conversation with `GET /v1/logs/conversations/{conversation_id}`. Filter by `channel`, `assistant_id`, `widget_id`, `api_key_id`, `member_id`, `mode` and `from`/`to`, and paginate with `cursor`. Members' own chats are visible to admins only, as lines without content, and never to an API key. Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "description": "Only the answers from these channels, comma-separated: `chat` (a member in the app's chat), `lookio_ai` (the in-app agent), `api` (an API key through REST, the CLI or the SDK), `mcp` (the MCP server), `widget` (a visitor of a widget). Default: all.", "minLength": 1 } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Only the answers of this assistant.", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "widget_id", "in": "query", "required": false, "schema": { "description": "Only this widget's answers.", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "api_key_id", "in": "query", "required": false, "schema": { "description": "Only the answers asked with this API key.", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "member_id", "in": "query", "required": false, "schema": { "description": "Only this member's answers (admins).", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "mode", "in": "query", "required": false, "schema": { "description": "Only this query mode (`flash`, `fast`, `deep`…).", "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "from", "in": "query", "required": false, "schema": { "description": "Only answers since this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Only answers until this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } } ], "security": [ { "bearerAuth": [ "usage:read" ] } ], "responses": { "200": { "description": "List the answer logs", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The answer's request id." }, "channel": { "type": "string", "enum": [ "chat", "lookio_ai", "api", "mcp", "widget" ], "description": "Where the question came from: `chat`, `lookio_ai`, `api`, `mcp` or `widget`. An API key's answer kept nowhere (`store: false`) shows as `api`." }, "assistant": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Null for Lookio AI, which answers about the workspace itself." }, "member": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The member who asked, for `chat` and `lookio_ai`." }, "api_key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The API key that asked." }, "widget": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The widget whose visitor asked." }, "end_user": { "description": "The widget visitor's id, or the `end_user` your product sent.", "type": [ "string", "null" ] }, "mode": { "type": "string", "description": "The query mode, or `agent-` for Lookio AI." }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What the answer cost." }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "How long it took, when the answer was kept." }, "conversation_id": { "description": "The conversation of a widget, API or MCP answer that was kept: read it with `GET /v1/logs/conversations/{conversation_id}`.", "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "channel", "assistant", "member", "api_key", "widget", "end_user", "mode", "credits", "duration_ms", "conversation_id", "created_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "invalid_cursor", "rate_limited", "internal_error" ] } }, "/v1/logs/answers/stats": { "get": { "operationId": "getLogAnswerStats", "x-surface-coverage": { "cli": "lookio logs answers --stats", "mcp": "get_answer_log_stats", "cliInputs": { "assistant_id": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "widget_id": { "inputs": [ "--widget" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "api_key_id": { "inputs": [ "--api-key" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "member_id": { "inputs": [ "--member" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Retrieve the figures of the answer logs", "description": "Answers, credits, average time and answers per channel, over the same filters as `GET /v1/logs/answers` (without `cursor` and `limit`). Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "description": "Only the answers from these channels, comma-separated: `chat` (a member in the app's chat), `lookio_ai` (the in-app agent), `api` (an API key through REST, the CLI or the SDK), `mcp` (the MCP server), `widget` (a visitor of a widget). Default: all.", "minLength": 1 } }, { "name": "assistant_id", "in": "query", "required": false, "schema": { "description": "Only the answers of this assistant.", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "widget_id", "in": "query", "required": false, "schema": { "description": "Only this widget's answers.", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "api_key_id", "in": "query", "required": false, "schema": { "description": "Only the answers asked with this API key.", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "member_id", "in": "query", "required": false, "schema": { "description": "Only this member's answers (admins).", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "mode", "in": "query", "required": false, "schema": { "description": "Only this query mode (`flash`, `fast`, `deep`…).", "type": "string", "minLength": 1, "maxLength": 40 } }, { "name": "from", "in": "query", "required": false, "schema": { "description": "Only answers since this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Only answers until this ISO 8601 date or timestamp.", "type": "string" } } ], "security": [ { "bearerAuth": [ "usage:read" ] } ], "responses": { "200": { "description": "Retrieve the figures of the answer logs", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "answers": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "average_duration_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Over the answers whose time was recorded; null when none was." }, "by_channel": { "type": "object", "properties": { "chat": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lookio_ai": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "api": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mcp": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "widget": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "chat", "lookio_ai", "api", "mcp", "widget" ], "additionalProperties": false, "description": "Answers per channel." } }, "required": [ "answers", "credits", "average_duration_ms", "by_channel" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "rate_limited", "internal_error" ] } }, "/v1/logs/indexing": { "get": { "operationId": "listLogIndexing", "x-surface-coverage": { "cli": "lookio logs indexing", "mcp": "list_indexing_logs", "cliInputs": { "resource_id": { "inputs": [ "--resource" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "q": { "inputs": [ "--query" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "List the indexing logs", "description": "Every indexing Lookio ran, one line each: a file read, a web page or a site's page fetched, a text added, and each update of them. Latest first, with its status (`indexed`, `failed` with the reason, `processing`…), what reading found (pages, words, passages, warnings) and how long it took. A site's sync re-reads its changed pages: those found `unchanged` are left out unless `include_unchanged=true`. Filter by `resource_id`, `status`, `source_type`, `q` and `from`/`to`, and paginate with `cursor`. Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "resource_id", "in": "query", "required": false, "schema": { "description": "Only this resource's indexings (a site: all its pages).", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Only these statuses, comma-separated: `queued`, `processing`, `indexed` (searchable now), `replaced` (indexed, then replaced by a newer indexing), `unchanged` (re-read, same text), `skipped` (a newer indexing finished first), `failed`. Default: all but `unchanged` and `skipped`.", "minLength": 1 } }, { "name": "source_type", "in": "query", "required": false, "schema": { "description": "Only resources of this kind.", "type": "string", "enum": [ "file", "url", "site", "text" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "description": "Words in the resource's title, the file's name, or the page's address or title.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "include_unchanged", "in": "query", "required": false, "schema": { "description": "Also list the pages a sync re-read and found unchanged. Default false.", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, { "name": "from", "in": "query", "required": false, "schema": { "description": "Only indexings started since this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Only indexings started until this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } } ], "security": [ { "bearerAuth": [ "resources:read" ] } ], "responses": { "200": { "description": "List the indexing logs", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The indexing's id (a version of the document)." }, "status": { "type": "string", "enum": [ "queued", "processing", "indexed", "replaced", "unchanged", "skipped", "failed" ] }, "resource": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "source_type": { "type": "string" } }, "required": [ "id", "title", "source_type" ], "additionalProperties": false }, "name": { "type": "string", "description": "What was read: a site page's title or address, a file's name, or the resource's title." }, "page_url": { "description": "A site page's address.", "type": [ "string", "null" ] }, "file": { "anyOf": [ { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "media_type": { "type": [ "string", "null" ] }, "byte_size": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "media_type", "byte_size" ], "additionalProperties": false }, { "type": "null" } ] }, "reader": { "description": "How the content was read (the parser or OCR used).", "type": [ "string", "null" ] }, "page_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "word_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "chunk_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Passages indexed." }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "What reading noticed, such as pages without text." }, "error": { "description": "Why it failed, for `failed`.", "type": [ "string", "null" ] }, "started_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "status", "resource", "name", "page_url", "file", "reader", "page_count", "word_count", "chunk_count", "warnings", "error", "started_at", "finished_at", "duration_ms" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "invalid_cursor", "rate_limited", "internal_error" ] } }, "/v1/logs/indexing/stats": { "get": { "operationId": "getLogIndexingStats", "x-surface-coverage": { "cli": "lookio logs indexing --stats", "mcp": "get_indexing_log_stats", "cliInputs": { "resource_id": { "inputs": [ "--resource" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "q": { "inputs": [ "--query" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Retrieve the figures of the indexing logs", "description": "Indexings, indexed, failed, in progress, unchanged and words indexed, over the same filters as `GET /v1/logs/indexing` (without `cursor` and `limit`). Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "resource_id", "in": "query", "required": false, "schema": { "description": "Only this resource's indexings (a site: all its pages).", "type": "string", "pattern": "^res_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Only these statuses, comma-separated: `queued`, `processing`, `indexed` (searchable now), `replaced` (indexed, then replaced by a newer indexing), `unchanged` (re-read, same text), `skipped` (a newer indexing finished first), `failed`. Default: all but `unchanged` and `skipped`.", "minLength": 1 } }, { "name": "source_type", "in": "query", "required": false, "schema": { "description": "Only resources of this kind.", "type": "string", "enum": [ "file", "url", "site", "text" ] } }, { "name": "q", "in": "query", "required": false, "schema": { "description": "Words in the resource's title, the file's name, or the page's address or title.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "include_unchanged", "in": "query", "required": false, "schema": { "description": "Also list the pages a sync re-read and found unchanged. Default false.", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, { "name": "from", "in": "query", "required": false, "schema": { "description": "Only indexings started since this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Only indexings started until this ISO 8601 date or timestamp.", "type": "string" } } ], "security": [ { "bearerAuth": [ "resources:read" ] } ], "responses": { "200": { "description": "Retrieve the figures of the indexing logs", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "indexed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Indexed, including those since replaced." }, "failed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "in_progress": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unchanged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Unchanged or skipped: counted only when the filters include them." }, "words_indexed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total", "indexed", "failed", "in_progress", "unchanged", "words_indexed" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "rate_limited", "internal_error" ] } }, "/v1/logs/activity": { "get": { "operationId": "listLogActivity", "x-surface-coverage": { "cli": "lookio logs activity", "mcp": "list_activity_log", "cliInputs": { "actor_id": { "inputs": [ "--actor" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "target_id": { "inputs": [ "--target" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "q": { "inputs": [ "--query" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "List the workspace activity", "description": "Who changed what in the workspace, latest first: resources added, edited, re-indexed or deleted, site rules and syncs, assistants and widgets created, edited, paused or deleted, tags renamed or deleted, members' access changed. Each line says who (a member, an API key, or Lookio itself for a scheduled sync), through which door (`app`, `api`, `cli`, `mcp`, `agent` for Lookio AI, `system`), and which fields changed (names only, never content). Filter by `actor_id`, `origin`, `target_type`, `target_id`, `action` and `from`/`to`, and paginate with `cursor`. Kept a year. Admins only, through a personal connection (the CLI's `lookio auth login`, an MCP client) with the `admin` scope: an API key never has it. Costs nothing.", "tags": [ "logs" ], "parameters": [ { "name": "actor_id", "in": "query", "required": false, "schema": { "description": "Only what this member (user id) or API key (key id) did.", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "origin", "in": "query", "required": false, "schema": { "type": "string", "description": "Only changes made through these doors, comma-separated: `app`, `api`, `cli`, `mcp`, `agent` (Lookio AI), `system` (Lookio itself, such as a scheduled sync).", "minLength": 1 } }, { "name": "target_type", "in": "query", "required": false, "schema": { "description": "Only changes to this kind of thing.", "type": "string", "enum": [ "resource", "assistant", "widget", "tag", "member" ] } }, { "name": "target_id", "in": "query", "required": false, "schema": { "description": "Only changes to this resource, assistant, widget or member.", "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "action", "in": "query", "required": false, "schema": { "description": "An exact action (`assistant.updated`) or every action on a kind (`assistant`).", "type": "string", "pattern": "^[a-z_]+(\\.[a-z_]+)?$" } }, { "name": "q", "in": "query", "required": false, "schema": { "description": "Words in the name of what changed.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "from", "in": "query", "required": false, "schema": { "description": "Only changes since this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "description": "Only changes until this ISO 8601 date or timestamp.", "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "List the workspace activity", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "action": { "type": "string", "description": "`.`, such as `resource.created`, `assistant.updated`, `widget.paused`, `site.synced`, `member.access_updated`." }, "summary": { "type": "string", "description": "The change in a few words, such as \"Edited Support\"." }, "actor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "member", "api_key", "system" ] }, "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "description": "Members only.", "type": [ "string", "null" ] } }, "required": [ "type", "id", "name" ], "additionalProperties": false }, "origin": { "type": "string", "description": "`app`, `api`, `cli`, `mcp`, `agent` (Lookio AI) or `system`." }, "target": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": [ "string", "null" ] }, "name": { "description": "Its name at the time of the change.", "type": [ "string", "null" ] } }, "required": [ "type", "id", "name" ], "additionalProperties": false }, "details": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "What changed, briefly: the fields edited (names only), counts, a sync's figures. Never content." }, "created_at": { "type": "string" } }, "required": [ "id", "action", "summary", "actor", "origin", "target", "details", "created_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "invalid_cursor", "rate_limited", "internal_error" ] } }, "/v1/widgets": { "get": { "operationId": "listWidgets", "x-surface-coverage": { "cli": "lookio widgets list", "mcp": "list_widgets" }, "summary": "List widgets", "description": "The widgets of the workspace, newest first, each with its settings, limits, the snippets to install it and this month's conversations, answers and credits. A widget is a chat box that shows one of your assistants to anonymous visitors on a website. A technical identity limited to some assistants sees only their widgets.", "tags": [ "widgets" ], "parameters": [], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "List widgets", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "assistant_id": { "type": "string" }, "assistant_name": { "description": "Null when the assistant was deleted: the widget answers nothing until you point it at another.", "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again." }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "properties": { "theme": { "default": "auto", "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "default": "#4F46E5", "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "default": "medium", "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "default": "corners", "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "default": "bottom-right", "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "default": "bubble", "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "default": "Ask AI", "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "default": "chat", "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "default": "medium", "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "default": true, "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "default": false, "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "launcher_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with `PUT /v1/widgets/{id}/images/launcher` or in the app. Null: the icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "favicon": { "default": null, "description": "Paid plans, read-only: the name of the hosted page's favicon, set with `PUT /v1/widgets/{id}/images/favicon` or in the app. Null: a favicon drawn from the widget's colour and icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "header_icon": { "default": "sparkles", "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "header_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with `PUT /v1/widgets/{id}/images/header` or in the app. Null: the header icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "title": { "default": "", "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "default": "", "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "default": "Hi! Ask me anything, I answer from our documentation.", "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "default": "Ask a question…", "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "default": [], "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "default": "AI answers can be wrong.", "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "default": "auto", "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "default": "numbered", "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "default": true, "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "default": true, "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "default": true, "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "default": true, "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "default": true, "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "default": false, "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "default": false, "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "required": [ "theme", "accent", "radius", "bubbles", "position", "launcher", "launcher_label", "launcher_icon", "launcher_size", "bar_icon", "bar_translucent", "launcher_image", "favicon", "header_icon", "header_image", "title", "subtitle", "greeting", "placeholder", "suggestions", "disclaimer", "language", "sources", "memory", "visitor_history", "feedback", "branding", "bubble", "embed", "hosted_page" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "monthly_credits_enabled": { "default": false, "type": "boolean" }, "per_visitor_hour": { "default": 40, "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "default": 150, "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "default": null, "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "required": [ "monthly_credits_enabled", "per_visitor_hour", "per_visitor_day", "monthly_credits" ], "additionalProperties": false }, "snippets": { "type": "object", "properties": { "bubble": { "type": "string", "description": "A `", "embed": "
\n", "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng", "iframe": "" }, "stats": { "conversations": 12, "answers": 31, "credits": 930 }, "created_via": "api", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "rate_limited", "internal_error" ] }, "post": { "operationId": "createWidget", "x-surface-coverage": { "cli": "lookio widgets create", "mcp": "create_widget", "cliInputs": { "assistant_id": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "allowed_domains": { "inputs": [ "--domain" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "settings": { "inputs": [ "--setting" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "limits": { "inputs": [ "--monthly-credits", "--limit-per-visitor-day", "--limit-per-visitor-hour", "--monthly-credits-enabled" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Create a widget", "description": "Creates a widget for an assistant and returns it with its `snippets`: paste `snippets.bubble` before `` for a launcher, `snippets.embed` where the chat should sit, link to `snippets.hosted` for a full page, or use `snippets.iframe` where scripts are refused. Only the bubble is on by default: `snippets.embed` and `snippets.iframe` work once `settings.embed` is true, `snippets.hosted` once `settings.hosted_page` is true; a format that is off answers 404. Add the websites that show it to `allowed_domains`: the browser refuses the bubble and the embed on any site not listed. Visitors' answers are charged to this workspace in the widget's `mode`; `limits` caps them per visitor and per month. Costs no credits itself.", "tags": [ "widgets" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "201": { "description": "Create a widget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "assistant_id": { "type": "string" }, "assistant_name": { "description": "Null when the assistant was deleted: the widget answers nothing until you point it at another.", "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again." }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "properties": { "theme": { "default": "auto", "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "default": "#4F46E5", "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "default": "medium", "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "default": "corners", "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "default": "bottom-right", "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "default": "bubble", "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "default": "Ask AI", "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "default": "chat", "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "default": "medium", "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "default": true, "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "default": false, "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "launcher_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with `PUT /v1/widgets/{id}/images/launcher` or in the app. Null: the icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "favicon": { "default": null, "description": "Paid plans, read-only: the name of the hosted page's favicon, set with `PUT /v1/widgets/{id}/images/favicon` or in the app. Null: a favicon drawn from the widget's colour and icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "header_icon": { "default": "sparkles", "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "header_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with `PUT /v1/widgets/{id}/images/header` or in the app. Null: the header icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "title": { "default": "", "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "default": "", "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "default": "Hi! Ask me anything, I answer from our documentation.", "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "default": "Ask a question…", "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "default": [], "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "default": "AI answers can be wrong.", "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "default": "auto", "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "default": "numbered", "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "default": true, "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "default": true, "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "default": true, "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "default": true, "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "default": true, "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "default": false, "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "default": false, "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "required": [ "theme", "accent", "radius", "bubbles", "position", "launcher", "launcher_label", "launcher_icon", "launcher_size", "bar_icon", "bar_translucent", "launcher_image", "favicon", "header_icon", "header_image", "title", "subtitle", "greeting", "placeholder", "suggestions", "disclaimer", "language", "sources", "memory", "visitor_history", "feedback", "branding", "bubble", "embed", "hosted_page" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "monthly_credits_enabled": { "default": false, "type": "boolean" }, "per_visitor_hour": { "default": 40, "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "default": 150, "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "default": null, "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "required": [ "monthly_credits_enabled", "per_visitor_hour", "per_visitor_day", "monthly_credits" ], "additionalProperties": false }, "snippets": { "type": "object", "properties": { "bubble": { "type": "string", "description": "A `", "embed": "
\n", "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng", "iframe": "" }, "stats": { "conversations": 12, "answers": 31, "credits": 930 }, "created_via": "api", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assistant_id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$", "description": "The assistant the widget speaks for. A technical identity limited to some assistants can only pick one of them." }, "name": { "description": "1 to 120 characters. Defaults to the assistant's name followed by `widget`.", "type": "string", "minLength": 1, "maxLength": 120 }, "mode": { "description": "The query mode every answer of this widget uses, so what it costs per answer (Eco 10, Flash 30 credits (the default), Deep 80). Default flash.", "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again.", "type": "string", "enum": [ "live", "paused" ] }, "allowed_domains": { "description": "The websites allowed to show the widget, as hosts (`docs.acme.com`) or `*.acme.com` for all subdomains (which also covers `acme.com`). Scheme, path and port are removed. The browser refuses to show the bubble and the embed on any other site, so a widget with no domain shows nowhere (the hosted page still works). Replaces the previous list.", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 } }, "settings": { "description": "Appearance, words and behaviour. Every field is optional and has a default.", "type": "object", "properties": { "theme": { "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "header_icon": { "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "title": { "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "additionalProperties": false }, "limits": { "description": "Spending and abuse limits. Every field is optional and has a default.", "type": "object", "properties": { "monthly_credits_enabled": { "type": "boolean" }, "per_visitor_hour": { "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "assistant_id" ], "additionalProperties": false }, "examples": { "minimal": { "summary": "A widget for an assistant", "value": { "assistant_id": "ast_66xcnwtzj8vt", "allowed_domains": [ "docs.acme.com", "*.acme.com" ] } }, "styled": { "summary": "Styled, with limits", "value": { "assistant_id": "ast_66xcnwtzj8vt", "name": "Docs chat", "mode": "eco", "allowed_domains": [ "docs.acme.com" ], "settings": { "accent": "#0F766E", "launcher": "pill", "launcher_label": "Ask the docs", "suggestions": [ "How do I get started?" ] }, "limits": { "per_visitor_hour": 10, "monthly_credits": 20000 } } } } } } } } }, "/v1/widgets/{widget_id}": { "get": { "operationId": "getWidget", "x-surface-coverage": { "cli": "lookio widgets get", "mcp": "get_widget" }, "summary": "Retrieve a widget", "description": "One widget with its settings, limits, snippets and this month's numbers.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "Retrieve a widget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "assistant_id": { "type": "string" }, "assistant_name": { "description": "Null when the assistant was deleted: the widget answers nothing until you point it at another.", "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again." }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "properties": { "theme": { "default": "auto", "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "default": "#4F46E5", "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "default": "medium", "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "default": "corners", "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "default": "bottom-right", "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "default": "bubble", "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "default": "Ask AI", "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "default": "chat", "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "default": "medium", "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "default": true, "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "default": false, "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "launcher_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with `PUT /v1/widgets/{id}/images/launcher` or in the app. Null: the icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "favicon": { "default": null, "description": "Paid plans, read-only: the name of the hosted page's favicon, set with `PUT /v1/widgets/{id}/images/favicon` or in the app. Null: a favicon drawn from the widget's colour and icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "header_icon": { "default": "sparkles", "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "header_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with `PUT /v1/widgets/{id}/images/header` or in the app. Null: the header icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "title": { "default": "", "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "default": "", "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "default": "Hi! Ask me anything, I answer from our documentation.", "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "default": "Ask a question…", "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "default": [], "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "default": "AI answers can be wrong.", "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "default": "auto", "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "default": "numbered", "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "default": true, "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "default": true, "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "default": true, "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "default": true, "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "default": true, "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "default": false, "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "default": false, "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "required": [ "theme", "accent", "radius", "bubbles", "position", "launcher", "launcher_label", "launcher_icon", "launcher_size", "bar_icon", "bar_translucent", "launcher_image", "favicon", "header_icon", "header_image", "title", "subtitle", "greeting", "placeholder", "suggestions", "disclaimer", "language", "sources", "memory", "visitor_history", "feedback", "branding", "bubble", "embed", "hosted_page" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "monthly_credits_enabled": { "default": false, "type": "boolean" }, "per_visitor_hour": { "default": 40, "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "default": 150, "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "default": null, "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "required": [ "monthly_credits_enabled", "per_visitor_hour", "per_visitor_day", "monthly_credits" ], "additionalProperties": false }, "snippets": { "type": "object", "properties": { "bubble": { "type": "string", "description": "A `", "embed": "
\n", "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng", "iframe": "" }, "stats": { "conversations": 12, "answers": 31, "credits": 930 }, "created_via": "api", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "resource_not_found", "rate_limited", "internal_error" ] }, "patch": { "operationId": "updateWidget", "x-surface-coverage": { "cli": "lookio widgets update", "mcp": "update_widget", "cliInputs": { "assistant_id": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "allowed_domains": { "inputs": [ "--domain" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "settings": { "inputs": [ "--setting" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "limits": { "inputs": [ "--monthly-credits", "--limit-per-visitor-day", "--limit-per-visitor-hour", "--monthly-credits-enabled" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Update a widget", "description": "Changes the fields you send and keeps the others, `settings` and `limits` field by field. Pause it with `status: \"paused\"` (it shows nothing and answers nothing until set live), point it at another assistant with `assistant_id`, or replace its `allowed_domains`.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "Update a widget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "assistant_id": { "type": "string" }, "assistant_name": { "description": "Null when the assistant was deleted: the widget answers nothing until you point it at another.", "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again." }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "properties": { "theme": { "default": "auto", "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "default": "#4F46E5", "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "default": "medium", "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "default": "corners", "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "default": "bottom-right", "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "default": "bubble", "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "default": "Ask AI", "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "default": "chat", "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "default": "medium", "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "default": true, "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "default": false, "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "launcher_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with `PUT /v1/widgets/{id}/images/launcher` or in the app. Null: the icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "favicon": { "default": null, "description": "Paid plans, read-only: the name of the hosted page's favicon, set with `PUT /v1/widgets/{id}/images/favicon` or in the app. Null: a favicon drawn from the widget's colour and icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "header_icon": { "default": "sparkles", "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "header_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with `PUT /v1/widgets/{id}/images/header` or in the app. Null: the header icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "title": { "default": "", "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "default": "", "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "default": "Hi! Ask me anything, I answer from our documentation.", "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "default": "Ask a question…", "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "default": [], "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "default": "AI answers can be wrong.", "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "default": "auto", "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "default": "numbered", "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "default": true, "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "default": true, "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "default": true, "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "default": true, "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "default": true, "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "default": false, "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "default": false, "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "required": [ "theme", "accent", "radius", "bubbles", "position", "launcher", "launcher_label", "launcher_icon", "launcher_size", "bar_icon", "bar_translucent", "launcher_image", "favicon", "header_icon", "header_image", "title", "subtitle", "greeting", "placeholder", "suggestions", "disclaimer", "language", "sources", "memory", "visitor_history", "feedback", "branding", "bubble", "embed", "hosted_page" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "monthly_credits_enabled": { "default": false, "type": "boolean" }, "per_visitor_hour": { "default": 40, "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "default": 150, "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "default": null, "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "required": [ "monthly_credits_enabled", "per_visitor_hour", "per_visitor_day", "monthly_credits" ], "additionalProperties": false }, "snippets": { "type": "object", "properties": { "bubble": { "type": "string", "description": "A `", "embed": "
\n", "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng", "iframe": "" }, "stats": { "conversations": 12, "answers": 31, "credits": 930 }, "created_via": "api", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "New name, 1 to 120 characters.", "type": "string", "minLength": 1, "maxLength": 120 }, "assistant_id": { "description": "Point the widget at another assistant.", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "mode": { "description": "The query mode every answer of this widget uses, so what it costs per answer (Eco 10, Flash 30 credits (the default), Deep 80). Default flash.", "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again.", "type": "string", "enum": [ "live", "paused" ] }, "allowed_domains": { "description": "The websites allowed to show the widget, as hosts (`docs.acme.com`) or `*.acme.com` for all subdomains (which also covers `acme.com`). Scheme, path and port are removed. The browser refuses to show the bubble and the embed on any other site, so a widget with no domain shows nowhere (the hosted page still works). Replaces the previous list.", "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 253 } }, "settings": { "description": "The settings you send are changed, the others are kept.", "type": "object", "properties": { "theme": { "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "header_icon": { "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "title": { "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "additionalProperties": false }, "limits": { "description": "The limits you send are changed, the others are kept.", "type": "object", "properties": { "monthly_credits_enabled": { "type": "boolean" }, "per_visitor_hour": { "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "examples": { "pause": { "summary": "Pause it", "value": { "status": "paused" } }, "accent": { "summary": "Change one setting", "value": { "settings": { "accent": "#0F766E" } } } } } } } }, "delete": { "operationId": "deleteWidget", "x-surface-coverage": { "cli": "lookio widgets delete", "mcp": "delete_widget" }, "summary": "Delete a widget", "description": "Deletes the widget and its visitors' conversations, and every page that embeds it stops showing it. What it spent stays in the usage figures. Cannot be undone; pause it instead to keep it.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:delete" ] } ], "responses": { "200": { "description": "Delete a widget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "wdg_xpatjpwt22fu", "deleted": true }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/widgets/{widget_id}/duplicate": { "post": { "operationId": "duplicateWidget", "x-surface-coverage": { "cli": "lookio widgets duplicate", "mcp": "duplicate_widget" }, "summary": "Duplicate a widget", "description": "Copies the widget under a new id, named \" (copy)\", with the same assistant, mode, status, allowed domains, settings, limits and images. The copy is installed nowhere yet: give it its own `snippets`. It counts against the plan's widget limit (`feature_not_available` when reached). Costs no credits.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "201": { "description": "Duplicate a widget", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "assistant_id": { "type": "string" }, "assistant_name": { "description": "Null when the assistant was deleted: the widget answers nothing until you point it at another.", "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again." }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "properties": { "theme": { "default": "auto", "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "default": "#4F46E5", "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "default": "medium", "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "default": "corners", "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "default": "bottom-right", "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "default": "bubble", "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "default": "Ask AI", "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "default": "chat", "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "default": "medium", "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "default": true, "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "default": false, "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "launcher_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with `PUT /v1/widgets/{id}/images/launcher` or in the app. Null: the icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "favicon": { "default": null, "description": "Paid plans, read-only: the name of the hosted page's favicon, set with `PUT /v1/widgets/{id}/images/favicon` or in the app. Null: a favicon drawn from the widget's colour and icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "header_icon": { "default": "sparkles", "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "header_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with `PUT /v1/widgets/{id}/images/header` or in the app. Null: the header icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "title": { "default": "", "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "default": "", "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "default": "Hi! Ask me anything, I answer from our documentation.", "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "default": "Ask a question…", "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "default": [], "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "default": "AI answers can be wrong.", "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "default": "auto", "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "default": "numbered", "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "default": true, "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "default": true, "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "default": true, "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "default": true, "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "default": true, "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "default": false, "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "default": false, "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "required": [ "theme", "accent", "radius", "bubbles", "position", "launcher", "launcher_label", "launcher_icon", "launcher_size", "bar_icon", "bar_translucent", "launcher_image", "favicon", "header_icon", "header_image", "title", "subtitle", "greeting", "placeholder", "suggestions", "disclaimer", "language", "sources", "memory", "visitor_history", "feedback", "branding", "bubble", "embed", "hosted_page" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "monthly_credits_enabled": { "default": false, "type": "boolean" }, "per_visitor_hour": { "default": 40, "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "default": 150, "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "default": null, "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "required": [ "monthly_credits_enabled", "per_visitor_hour", "per_visitor_day", "monthly_credits" ], "additionalProperties": false }, "snippets": { "type": "object", "properties": { "bubble": { "type": "string", "description": "A `", "embed": "
\n", "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng", "iframe": "" }, "stats": { "conversations": 12, "answers": 31, "credits": 930 }, "created_via": "api", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "permission_denied", "invalid_parameter", "resource_not_found", "conflict", "rate_limited", "internal_error" ] } }, "/v1/widgets/{widget_id}/images/{kind}": { "put": { "operationId": "setWidgetImage", "x-surface-coverage": { "cli": "lookio widgets set-image", "mcp": null, "mcpReason": "An image is bytes the model does not hold: an MCP tool argument would carry it as base64 inside the model's context, which is slow, costly and capped. Agents set it through the CLI or the REST route." }, "summary": "Set a widget's launcher image, header image or favicon", "description": "Send the image's bytes as the request body, not multipart; `Content-Length` is required. `kind` is `launcher` (shown in place of the launcher's icon), `header` (shown in place of the icon in the chat's header) or `favicon` (the hosted page's). PNG, JPEG, WebP or GIF, and ICO for the favicon, up to 256 KB; the format is read from the bytes, whatever the `Content-Type`, and SVG is refused. Paid plans only (`feature_not_available` on the free plan). Replaces the previous image and returns the widget, whose `settings.launcher_image` or `settings.favicon` now names it. Costs no credits.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "launcher", "header", "favicon" ] } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "Set a widget's launcher image, header image or favicon", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "assistant_id": { "type": "string" }, "assistant_name": { "description": "Null when the assistant was deleted: the widget answers nothing until you point it at another.", "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again." }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "properties": { "theme": { "default": "auto", "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "default": "#4F46E5", "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "default": "medium", "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "default": "corners", "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "default": "bottom-right", "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "default": "bubble", "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "default": "Ask AI", "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "default": "chat", "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "default": "medium", "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "default": true, "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "default": false, "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "launcher_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with `PUT /v1/widgets/{id}/images/launcher` or in the app. Null: the icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "favicon": { "default": null, "description": "Paid plans, read-only: the name of the hosted page's favicon, set with `PUT /v1/widgets/{id}/images/favicon` or in the app. Null: a favicon drawn from the widget's colour and icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "header_icon": { "default": "sparkles", "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "header_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with `PUT /v1/widgets/{id}/images/header` or in the app. Null: the header icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "title": { "default": "", "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "default": "", "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "default": "Hi! Ask me anything, I answer from our documentation.", "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "default": "Ask a question…", "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "default": [], "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "default": "AI answers can be wrong.", "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "default": "auto", "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "default": "numbered", "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "default": true, "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "default": true, "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "default": true, "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "default": true, "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "default": true, "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "default": false, "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "default": false, "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "required": [ "theme", "accent", "radius", "bubbles", "position", "launcher", "launcher_label", "launcher_icon", "launcher_size", "bar_icon", "bar_translucent", "launcher_image", "favicon", "header_icon", "header_image", "title", "subtitle", "greeting", "placeholder", "suggestions", "disclaimer", "language", "sources", "memory", "visitor_history", "feedback", "branding", "bubble", "embed", "hosted_page" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "monthly_credits_enabled": { "default": false, "type": "boolean" }, "per_visitor_hour": { "default": 40, "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "default": 150, "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "default": null, "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "required": [ "monthly_credits_enabled", "per_visitor_hour", "per_visitor_day", "monthly_credits" ], "additionalProperties": false }, "snippets": { "type": "object", "properties": { "bubble": { "type": "string", "description": "A `", "embed": "
\n", "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng", "iframe": "" }, "stats": { "conversations": 12, "answers": 31, "credits": 930 }, "created_via": "api", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "permission_denied", "invalid_request", "invalid_parameter", "request_too_large", "resource_not_found", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "description": "The image's bytes, unencoded. `Content-Length` is required.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "*/*": { "schema": { "type": "string", "format": "binary" } } } } }, "delete": { "operationId": "deleteWidgetImage", "x-surface-coverage": { "cli": "lookio widgets clear-image", "mcp": "clear_widget_image" }, "summary": "Remove a widget's launcher image or favicon", "description": "Removes the image and deletes its file: the launcher shows its icon again, and the hosted page a favicon drawn from the widget's colour and icon. Returns the widget. Nothing to remove is not an error. Costs no credits.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "launcher", "header", "favicon" ] } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "Remove a widget's launcher image or favicon", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "assistant_id": { "type": "string" }, "assistant_name": { "description": "Null when the assistant was deleted: the widget answers nothing until you point it at another.", "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` answers visitors; `paused` shows nothing and answers nothing, until set live again." }, "allowed_domains": { "type": "array", "items": { "type": "string" } }, "settings": { "type": "object", "properties": { "theme": { "default": "auto", "description": "`light`, `dark`, or `auto` to follow the visitor's system.", "type": "string", "enum": [ "light", "dark", "auto" ] }, "accent": { "default": "#4F46E5", "description": "The brand colour of the launcher and the buttons, as `#RRGGBB`.", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "radius": { "default": "medium", "description": "How round the corners are: `none`, `small`, `medium` or `large`.", "type": "string", "enum": [ "none", "small", "medium", "large" ] }, "bubbles": { "default": "corners", "description": "The shape of the visitor's message bubbles and the suggestion chips: `corners` (default) follows `radius`, `round` makes them fully round whatever the corners are. Omit it to leave it as it is.", "type": "string", "enum": [ "corners", "round" ] }, "position": { "default": "bottom-right", "description": "Which corner of the page the bubble sits in: `bottom-right` or `bottom-left`.", "type": "string", "enum": [ "bottom-right", "bottom-left" ] }, "launcher": { "default": "bubble", "description": "`bubble`: a round button in a corner. `pill`: a button with `launcher_label`. `bar`: a bar centered at the bottom of the page, showing the `placeholder`, that opens the chat in the middle of the screen (`position` does not apply).", "type": "string", "enum": [ "bubble", "pill", "bar" ] }, "launcher_label": { "default": "Ask AI", "description": "The text of the pill launcher, up to 40 characters.", "type": "string", "maxLength": 40 }, "launcher_icon": { "default": "chat", "description": "The launcher's icon: `chat` (default), `message`, `help`, `sparkles`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support" ] }, "launcher_size": { "default": "medium", "description": "The launcher's size, whatever its style: `small`, `medium` (default) or `large`.", "type": "string", "enum": [ "small", "medium", "large" ] }, "bar_icon": { "default": true, "description": "The `bar` launcher: show the icon at its start (default). Off: a plain field.", "type": "boolean" }, "bar_translucent": { "default": false, "description": "The `bar` launcher: see-through, with the page blurred behind it. Off (default): a solid bar.", "type": "boolean" }, "launcher_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the launcher's icon, set with `PUT /v1/widgets/{id}/images/launcher` or in the app. Null: the icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "favicon": { "default": null, "description": "Paid plans, read-only: the name of the hosted page's favicon, set with `PUT /v1/widgets/{id}/images/favicon` or in the app. Null: a favicon drawn from the widget's colour and icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "header_icon": { "default": "sparkles", "description": "The avatar in the chat's header, apart from the launcher's icon: `sparkles` (default), `chat`, `message`, `help`, `bot`, `search`, `book`, `bulb`, `bolt`, `heart`, `star` or `support`; `none` shows no avatar at all.", "type": "string", "enum": [ "chat", "message", "help", "sparkles", "bot", "search", "book", "bulb", "bolt", "heart", "star", "support", "none" ] }, "header_image": { "default": null, "description": "Paid plans, read-only: the name of the image shown in place of the icon in the chat's header, set with `PUT /v1/widgets/{id}/images/header` or in the app. Null: the header icon.", "anyOf": [ { "type": "string", "pattern": "^(launcher|header|favicon)-[a-f0-9]{12}\\.(png|jpg|webp|gif|ico)$" }, { "type": "null" } ] }, "title": { "default": "", "description": "The chat's title, up to 60 characters. Empty means the assistant's name.", "type": "string", "maxLength": 60 }, "subtitle": { "default": "", "description": "A line under the chat's title, up to 80 characters, like `Available 24/7`. Empty (default): none, and the title sits centered alone. Omit it to leave it as it is.", "type": "string", "maxLength": 80 }, "greeting": { "default": "Hi! Ask me anything, I answer from our documentation.", "description": "The first message the visitor sees, up to 500 characters.", "type": "string", "maxLength": 500 }, "placeholder": { "default": "Ask a question…", "description": "The hint in the question box, up to 80 characters.", "type": "string", "maxLength": 80 }, "suggestions": { "default": [], "description": "Up to 4 example questions (120 characters each) shown before the first question.", "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "disclaimer": { "default": "AI answers can be wrong.", "description": "The small print under the chat, up to 200 characters. Empty hides it.", "type": "string", "maxLength": 200 }, "language": { "default": "auto", "description": "The language of the widget's own words (buttons, notices): `auto` follows the visitor, or `en`, `fr`, `de`, `es`, `it`, `pt`. Answers always follow the visitor's language.", "type": "string", "enum": [ "auto", "en", "fr", "de", "es", "it", "pt" ] }, "sources": { "default": "numbered", "description": "How answers show their sources: `numbered` ([1] markers and a source list with links to web pages), `numbered_no_links` (the same without any address), `inline_links` (the answer links its own words to the source pages, no list; describe the style in the assistant's context) or `none`.", "type": "string", "enum": [ "numbered", "numbered_no_links", "inline_links", "none" ] }, "memory": { "default": true, "description": "Follow-up questions see the conversation so far.", "type": "boolean" }, "visitor_history": { "default": true, "description": "Visitors find their past chats when they come back on the same browser (a random id kept in the chat frame's own storage). Off: nothing is kept in the browser and every visit starts fresh.", "type": "boolean" }, "feedback": { "default": true, "description": "Thumbs up and down under each answer, with an optional word on what was wrong after a thumbs down. Read them in the workspace's logs: `GET /v1/logs/conversations?widget_id=…&rating=down` lists the conversations where visitors were not satisfied.", "type": "boolean" }, "branding": { "default": true, "description": "Show \"Powered by Lookio\". Only paid plans may turn it off.", "type": "boolean" }, "bubble": { "default": true, "description": "The chat bubble format: a launcher in a corner of the page that opens the chat. On by default. Off: the loader draws nothing.", "type": "boolean" }, "embed": { "default": false, "description": "The in-page format: the chat inside a container of your page (`snippets.embed`, or `snippets.iframe`). Off by default; off, the frame answers 404.", "type": "boolean" }, "hosted_page": { "default": false, "description": "The hosted page format: a full-page chat at `snippets.hosted`, to link to. Off by default; off, the page answers 404.", "type": "boolean" } }, "required": [ "theme", "accent", "radius", "bubbles", "position", "launcher", "launcher_label", "launcher_icon", "launcher_size", "bar_icon", "bar_translucent", "launcher_image", "favicon", "header_icon", "header_image", "title", "subtitle", "greeting", "placeholder", "suggestions", "disclaimer", "language", "sources", "memory", "visitor_history", "feedback", "branding", "bubble", "embed", "hosted_page" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "monthly_credits_enabled": { "default": false, "type": "boolean" }, "per_visitor_hour": { "default": 40, "description": "Questions one visitor may ask per hour, 1 to 500.", "type": "integer", "minimum": 1, "maximum": 500 }, "per_visitor_day": { "default": 150, "description": "Questions one visitor may ask per day, 1 to 2,000, and not fewer than the hourly limit.", "type": "integer", "minimum": 1, "maximum": 2000 }, "monthly_credits": { "default": null, "description": "Credits the widget may spend per calendar month (UTC), 10 to 10,000,000. Null: no ceiling beyond the workspace's balance. When it is reached the widget stops answering until the month turns.", "anyOf": [ { "type": "integer", "minimum": 10, "maximum": 10000000 }, { "type": "null" } ] } }, "required": [ "monthly_credits_enabled", "per_visitor_hour", "per_visitor_day", "monthly_credits" ], "additionalProperties": false }, "snippets": { "type": "object", "properties": { "bubble": { "type": "string", "description": "A `", "embed": "
\n", "hosted": "https://widget.lookio.app/w/wdg_j36h6kb8tyng", "iframe": "" }, "stats": { "conversations": 12, "answers": 31, "credits": 930 }, "created_via": "api", "created_at": "2026-10-12T09:30:00.000Z", "updated_at": "2026-10-12T09:30:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/widgets/{widget_id}/conversations": { "get": { "operationId": "listWidgetConversations", "x-surface-coverage": { "cli": "lookio widgets conversations", "mcp": "list_widget_conversations" }, "summary": "List a widget's conversations", "description": "The conversations anonymous visitors had through this widget, latest first: the same as `GET /v1/logs/conversations?widget_id=…`, with who (`end_user` is the visitor's random id), how many messages, the visitors' thumbs and what it cost. Paginate with `cursor`: pass `next_cursor` from the previous page. Visitors' conversations are kept 90 days.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Pass `next_cursor` from the previous page, unchanged.", "type": "string", "minLength": 1, "maxLength": 40 } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "List a widget's conversations", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "channel": { "type": "string", "enum": [ "widget", "api", "mcp" ], "description": "`widget`: a visitor on your website. `api`: an API key through REST, the CLI or the SDK. `mcp`: an API key through the MCP server." }, "title": { "type": "string", "description": "The first question." }, "assistant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null when the assistant was deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, "widget": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The widget, for the `widget` channel." }, "api_key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null once the key is deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The API key, for the `api` and `mcp` channels." }, "end_user": { "description": "Who was asking: a widget visitor's random id, or the `end_user` the product sent. Null when an API key sent none.", "type": [ "string", "null" ] }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Questions and answers together." }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What this conversation's answers cost." }, "thumbs_up": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "thumbs_down": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "description": "The last activity. Conversations are listed by it, latest first." }, "locked": { "type": "boolean", "description": "Older than the plan keeps conversations readable (7 days on Free, 90 on Starter, 1 year on Pro, from the last activity). Its text is hidden, not yet deleted: `title` is then a date and `messages` is empty, and a higher plan shows it again." } }, "required": [ "id", "channel", "title", "assistant", "widget", "api_key", "end_user", "message_count", "credits", "thumbs_up", "thumbs_down", "created_at", "updated_at", "locked" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_parameter", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/widgets/{widget_id}/conversations/{conversation_id}": { "get": { "operationId": "getWidgetConversation", "x-surface-coverage": { "cli": "lookio widgets conversations", "mcp": "get_widget_conversation" }, "summary": "Retrieve a widget conversation", "description": "One visitor conversation with its messages, citations, cost, duration and the visitor's thumb and comment on each answer: the same as `GET /v1/logs/conversations/{conversation_id}`, for a conversation of this widget.", "tags": [ "widgets" ], "parameters": [ { "name": "widget_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^wdg_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "name": "conversation_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:write" ] } ], "responses": { "200": { "description": "Retrieve a widget conversation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^cnv_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "channel": { "type": "string", "enum": [ "widget", "api", "mcp" ], "description": "`widget`: a visitor on your website. `api`: an API key through REST, the CLI or the SDK. `mcp`: an API key through the MCP server." }, "title": { "type": "string", "description": "The first question." }, "assistant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null when the assistant was deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, "widget": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The widget, for the `widget` channel." }, "api_key": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "description": "Null once the key is deleted.", "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The API key, for the `api` and `mcp` channels." }, "end_user": { "description": "Who was asking: a widget visitor's random id, or the `end_user` the product sent. Null when an API key sent none.", "type": [ "string", "null" ] }, "message_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Questions and answers together." }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "What this conversation's answers cost." }, "thumbs_up": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "thumbs_down": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" }, "updated_at": { "type": "string", "description": "The last activity. Conversations are listed by it, latest first." }, "locked": { "type": "boolean", "description": "Older than the plan keeps conversations readable (7 days on Free, 90 on Starter, 1 year on Pro, from the last activity). Its text is hidden, not yet deleted: `title` is then a date and `messages` is empty, and a higher plan shows it again." }, "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "resource_id": { "type": "string", "description": "The cited resource. Empty for a public assistant of another workspace: its resources stay its own." }, "title": { "type": "string" }, "text": { "type": "string", "description": "The passage the answer relies on." }, "n": { "description": "The number the answer cites it by, as [1].", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "section": { "type": "array", "items": { "type": "string" } }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "source": { "description": "The cited resource's source, when it has one.", "type": "string" } }, "required": [ "resource_id", "title", "text" ], "additionalProperties": false }, "description": "The passages the answer relied on." }, "credit_cost": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Answers only: what it cost." }, "mode": { "description": "Answers only: the query mode.", "type": [ "string", "null" ] }, "duration_ms": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Answers only: how long it took to write." }, "rating": { "anyOf": [ { "type": "string", "enum": [ "up", "down" ] }, { "type": "null" } ], "description": "The thumb on an answer, from the visitor or forwarded by your product." }, "rating_comment": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "role", "content", "citations", "credit_cost", "mode", "duration_ms", "rating", "rating_comment", "created_at" ], "additionalProperties": false } } }, "required": [ "id", "channel", "title", "assistant", "widget", "api_key", "end_user", "message_count", "credits", "thumbs_up", "thumbs_down", "created_at", "updated_at", "locked", "messages" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/tags": { "get": { "operationId": "listTags", "x-surface-coverage": { "cli": "lookio tags list", "mcp": "list_tags" }, "summary": "List the tags in use", "description": "Every tag carried by a resource or followed by an assistant, with how many of each, sorted by name. There is no tag object: a tag exists while something uses it.", "tags": [ "tags" ], "parameters": [], "security": [ { "bearerAuth": [ "resources:read" ] } ], "responses": { "200": { "description": "List the tags in use", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "tag": { "type": "string" }, "resources": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many resources carry this tag." }, "assistants": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many assistants follow this tag." } }, "required": [ "tag", "resources", "assistants" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ] }, "examples": { "default": { "value": { "data": [ { "tag": "faq", "resources": 4, "assistants": 1 } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "rate_limited", "internal_error" ] } }, "/v1/tags/rename": { "post": { "operationId": "renameTag", "x-surface-coverage": { "cli": "lookio tags rename", "mcp": "rename_tag" }, "summary": "Rename a tag", "description": "Renames the tag on every resource and assistant that carries it, in one batch. When the new name already exists the two tags are merged. Workspace admins only, through a personal connection.", "tags": [ "tags" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Rename a tag", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tag": { "type": "string" }, "resources": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many resources carry this tag." }, "assistants": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many assistants follow this tag." } }, "required": [ "tag", "resources", "assistants" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The tag to rename, exactly as listed." }, "to": { "type": "string", "minLength": 1, "maxLength": 60, "description": "The new name. When it already exists, the two tags are merged." } }, "required": [ "from", "to" ] } } } } } }, "/v1/tags/{tag}": { "delete": { "operationId": "deleteTag", "x-surface-coverage": { "cli": "lookio tags delete", "mcp": "delete_tag" }, "summary": "Delete a tag", "description": "Removes the tag from every resource and assistant. The resources stay, but an assistant that followed the tag no longer uses the resources it brought. The tag goes URL-encoded in the path. Workspace admins only, through a personal connection.", "tags": [ "tags" ], "parameters": [ { "name": "tag", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Delete a tag", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tag": { "type": "string" }, "resources": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many resources carry this tag." }, "assistants": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many assistants follow this tag." } }, "required": [ "tag", "resources", "assistants" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/members": { "get": { "operationId": "listMembers", "x-surface-coverage": { "cli": "lookio members list", "mcp": "list_members" }, "summary": "List members and their Lookio permissions", "description": "Every member with what they may do and which assistants they may use. Workspace admins only, through a personal connection.", "tags": [ "members" ], "parameters": [], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "List members and their Lookio permissions", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "permissions": { "type": "object", "properties": { "resources_list": { "type": "boolean" }, "resources_create": { "type": "boolean" }, "resources_edit": { "type": "boolean" }, "resources_delete": { "type": "boolean" }, "assistants_create": { "type": "boolean" }, "assistants_edit": { "type": "boolean" }, "assistants_delete": { "type": "boolean" }, "api": { "type": "boolean" }, "mcp": { "type": "boolean" } }, "required": [ "resources_list", "resources_create", "resources_edit", "resources_delete", "assistants_create", "assistants_edit", "assistants_delete", "api", "mcp" ], "additionalProperties": false }, "assistant_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The assistants this member may use; null is all of them." } }, "required": [ "user_id", "email", "name", "role", "permissions", "assistant_ids" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "rate_limited", "internal_error" ] } }, "/v1/members/{user_id}": { "patch": { "operationId": "updateMemberPermissions", "x-surface-coverage": { "cli": "lookio members set", "mcp": "set_member_permissions", "cliInputs": { "permissions": { "inputs": [ "--allow", "--deny" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." }, "assistant_ids": { "inputs": [ "--assistants" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Change a member's permissions", "description": "Sets the permissions you send (snake_case: `resources_list`, `resources_create`, `resources_edit`, `resources_delete`, `assistants_create`, `assistants_edit`, `assistants_delete`, `api`, `mcp`), keeps the others, and replaces the member's assistants. Paid plans only: on the free plan every member may do everything. The change applies to the member's connections at once.", "tags": [ "members" ], "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Change a member's permissions", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "user_id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "permissions": { "type": "object", "properties": { "resources_list": { "type": "boolean" }, "resources_create": { "type": "boolean" }, "resources_edit": { "type": "boolean" }, "resources_delete": { "type": "boolean" }, "assistants_create": { "type": "boolean" }, "assistants_edit": { "type": "boolean" }, "assistants_delete": { "type": "boolean" }, "api": { "type": "boolean" }, "mcp": { "type": "boolean" } }, "required": [ "resources_list", "resources_create", "resources_edit", "resources_delete", "assistants_create", "assistants_edit", "assistants_delete", "api", "mcp" ], "additionalProperties": false }, "assistant_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "The assistants this member may use; null is all of them." } }, "required": [ "user_id", "email", "name", "role", "permissions", "assistant_ids" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "admin_required", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "permissions": { "type": "object", "properties": { "resources_list": { "type": "boolean" }, "resources_create": { "type": "boolean" }, "resources_edit": { "type": "boolean" }, "resources_delete": { "type": "boolean" }, "assistants_create": { "type": "boolean" }, "assistants_edit": { "type": "boolean" }, "assistants_delete": { "type": "boolean" }, "api": { "type": "boolean" }, "mcp": { "type": "boolean" } }, "additionalProperties": false, "description": "Each permission to set. Missing ones are refused for members on the Pro plan." }, "assistant_ids": { "anyOf": [ { "maxItems": 500, "type": "array", "items": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "type": "null" } ], "description": "The assistants this member may use; null for all, including future ones." } }, "required": [ "permissions", "assistant_ids" ] }, "examples": { "support": { "summary": "Let a member use the API, not MCP", "value": { "permissions": { "api": true, "mcp": false }, "assistant_ids": null } } } } } } } }, "/v1/accesses": { "get": { "operationId": "listAccesses", "x-surface-coverage": { "cli": "lookio accesses list", "mcp": "list_accesses" }, "summary": "List accesses", "description": "The workspace's accesses, newest first. An access shares some of your assistants with people outside the workspace, through its own MCP server and HTTP API (`urls`), and the workspace pays for their questions. Callers see each assistant's name and the description you wrote, never its context, guidelines or resources. Admins only. Costs nothing.", "tags": [ "accesses" ], "parameters": [], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "List accesses", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^acc_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about the access as a whole." }, "protection": { "type": "string", "enum": [ "public", "keys" ], "description": "`public`: anyone with the address may call it. `keys`: every call needs one of its access keys (Pro plan)." }, "status": { "type": "string", "enum": [ "live", "paused" ] }, "capabilities": { "type": "object", "properties": { "modes": { "type": "array", "items": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "description": "The query modes callers may ask in, at their usual prices. Empty turns answers off." }, "passages": { "type": "boolean", "description": "Whether callers may search the passages without an answer (1 credit a search)." } }, "required": [ "modes", "passages" ], "additionalProperties": false }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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." }, "assistants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about it. Its context, guidelines and resources are never shown to them." }, "reads_nothing": { "type": "boolean", "description": "It reads no searchable resource, so callers asking it are refused (for free)." } }, "required": [ "id", "name", "description", "reads_nothing" ], "additionalProperties": false } }, "key_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stats": { "type": "object", "properties": { "today_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today_credits", "month_credits", "month_requests" ], "additionalProperties": false }, "blocked": { "anyOf": [ { "type": "string", "enum": [ "paused", "keys_need_plan", "no_keys", "no_assistants" ] }, { "type": "null" } ], "description": "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." }, "urls": { "type": "object", "properties": { "help": { "type": "string", "description": "Its help, for people and agents: what it holds and how to call it (`GET`)." }, "mcp": { "type": "string", "description": "Its MCP server (Streamable HTTP)." }, "assistants": { "type": "string" }, "ask": { "type": "string" }, "search": { "type": "string" } }, "required": [ "help", "mcp", "assistants", "ask", "search" ], "additionalProperties": false }, "keys": { "description": "Its access keys, on a single access (not in the list).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aky_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string", "description": "Who the key is for." }, "prefix": { "type": "string", "description": "The start of the key (`ak_live_`), to recognise it. The whole key is shown once, at creation." }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthly_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spent": { "type": "object", "properties": { "today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today", "month" ], "additionalProperties": false, "description": "Credits spent with this key, this UTC day and month." }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "daily_credits", "monthly_credits", "spent", "last_used_at", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "protection", "status", "capabilities", "daily_credits", "monthly_credits", "assistants", "key_count", "stats", "blocked", "urls", "created_at", "updated_at" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "request_id" ] }, "examples": { "default": { "value": { "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" } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "resource_not_found", "rate_limited", "internal_error" ] }, "post": { "operationId": "createAccess", "x-surface-coverage": { "cli": "lookio accesses create", "mcp": "create_access", "cliInputs": { "assistants": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Create an access", "description": "Shares the assistants you list with people outside the workspace. `public` (default): anyone with its address may call it. `keys`: every call needs one of its access keys (create them with `POST /v1/accesses/{id}/keys`; Pro plan). `modes` and `passages` say what callers may do; `daily_credits` and `monthly_credits` cap what the whole access spends. Give callers `urls.mcp` (an MCP server) or `urls.help` (the HTTP API and its help). Costs nothing until it is called.", "tags": [ "accesses" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "201": { "description": "Create an access", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^acc_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about the access as a whole." }, "protection": { "type": "string", "enum": [ "public", "keys" ], "description": "`public`: anyone with the address may call it. `keys`: every call needs one of its access keys (Pro plan)." }, "status": { "type": "string", "enum": [ "live", "paused" ] }, "capabilities": { "type": "object", "properties": { "modes": { "type": "array", "items": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "description": "The query modes callers may ask in, at their usual prices. Empty turns answers off." }, "passages": { "type": "boolean", "description": "Whether callers may search the passages without an answer (1 credit a search)." } }, "required": [ "modes", "passages" ], "additionalProperties": false }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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." }, "assistants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about it. Its context, guidelines and resources are never shown to them." }, "reads_nothing": { "type": "boolean", "description": "It reads no searchable resource, so callers asking it are refused (for free)." } }, "required": [ "id", "name", "description", "reads_nothing" ], "additionalProperties": false } }, "key_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stats": { "type": "object", "properties": { "today_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today_credits", "month_credits", "month_requests" ], "additionalProperties": false }, "blocked": { "anyOf": [ { "type": "string", "enum": [ "paused", "keys_need_plan", "no_keys", "no_assistants" ] }, { "type": "null" } ], "description": "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." }, "urls": { "type": "object", "properties": { "help": { "type": "string", "description": "Its help, for people and agents: what it holds and how to call it (`GET`)." }, "mcp": { "type": "string", "description": "Its MCP server (Streamable HTTP)." }, "assistants": { "type": "string" }, "ask": { "type": "string" }, "search": { "type": "string" } }, "required": [ "help", "mcp", "assistants", "ask", "search" ], "additionalProperties": false }, "keys": { "description": "Its access keys, on a single access (not in the list).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aky_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string", "description": "Who the key is for." }, "prefix": { "type": "string", "description": "The start of the key (`ak_live_`), to recognise it. The whole key is shown once, at creation." }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthly_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spent": { "type": "object", "properties": { "today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today", "month" ], "additionalProperties": false, "description": "Credits spent with this key, this UTC day and month." }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "daily_credits", "monthly_credits", "spent", "last_used_at", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "protection", "status", "capabilities", "daily_credits", "monthly_credits", "assistants", "key_count", "stats", "blocked", "urls", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "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": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "admin_required", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "What callers see as its name, in their MCP client and on its help page. 1 to 120 characters." }, "description": { "description": "What callers read about the access as a whole. Up to 2,000 characters.", "type": "string", "maxLength": 2000 }, "assistants": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "description": { "description": "What callers read about it: what it answers, from what. Up to 1,000 characters.", "type": "string", "maxLength": 1000 } }, "required": [ "id" ] }, "description": "The assistants it offers, in order (1 to 20). Their names are shown as they are." }, "protection": { "description": "Default `public`. `keys` is on the Pro plan.", "type": "string", "enum": [ "public", "keys" ] }, "status": { "description": "`live` (default) answers; `paused` refuses every call until set live again.", "type": "string", "enum": [ "live", "paused" ] }, "modes": { "description": "The query modes callers may use, at their usual prices. Default `[\"flash\"]`; empty turns answers off (passages must then be on).", "type": "array", "items": { "type": "string", "enum": [ "eco", "flash", "deep" ] } }, "passages": { "description": "Default false.", "type": "boolean" }, "daily_credits": { "description": "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.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "monthly_credits": { "description": "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.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] } }, "required": [ "name", "assistants" ], "additionalProperties": false }, "examples": { "public": { "summary": "A public access to one assistant", "value": { "name": "Acme docs", "assistants": [ { "id": "ast_66xcnwtzj8vt", "description": "Answers from the product documentation." } ] } }, "protected": { "summary": "Protected by keys, two modes and passages, a monthly ceiling", "value": { "name": "Acme docs", "assistants": [ { "id": "ast_66xcnwtzj8vt" } ], "protection": "keys", "modes": [ "flash", "deep" ], "passages": true, "monthly_credits": 200000 } } } } } } } }, "/v1/accesses/{access_id}": { "get": { "operationId": "getAccess", "x-surface-coverage": { "cli": "lookio accesses get", "mcp": "get_access" }, "summary": "Retrieve an access", "description": "One access with its assistants, capabilities, ceilings, this month's spending and its keys (never their secrets).", "tags": [ "accesses" ], "parameters": [ { "name": "access_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Retrieve an access", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^acc_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about the access as a whole." }, "protection": { "type": "string", "enum": [ "public", "keys" ], "description": "`public`: anyone with the address may call it. `keys`: every call needs one of its access keys (Pro plan)." }, "status": { "type": "string", "enum": [ "live", "paused" ] }, "capabilities": { "type": "object", "properties": { "modes": { "type": "array", "items": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "description": "The query modes callers may ask in, at their usual prices. Empty turns answers off." }, "passages": { "type": "boolean", "description": "Whether callers may search the passages without an answer (1 credit a search)." } }, "required": [ "modes", "passages" ], "additionalProperties": false }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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." }, "assistants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about it. Its context, guidelines and resources are never shown to them." }, "reads_nothing": { "type": "boolean", "description": "It reads no searchable resource, so callers asking it are refused (for free)." } }, "required": [ "id", "name", "description", "reads_nothing" ], "additionalProperties": false } }, "key_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stats": { "type": "object", "properties": { "today_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today_credits", "month_credits", "month_requests" ], "additionalProperties": false }, "blocked": { "anyOf": [ { "type": "string", "enum": [ "paused", "keys_need_plan", "no_keys", "no_assistants" ] }, { "type": "null" } ], "description": "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." }, "urls": { "type": "object", "properties": { "help": { "type": "string", "description": "Its help, for people and agents: what it holds and how to call it (`GET`)." }, "mcp": { "type": "string", "description": "Its MCP server (Streamable HTTP)." }, "assistants": { "type": "string" }, "ask": { "type": "string" }, "search": { "type": "string" } }, "required": [ "help", "mcp", "assistants", "ask", "search" ], "additionalProperties": false }, "keys": { "description": "Its access keys, on a single access (not in the list).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aky_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string", "description": "Who the key is for." }, "prefix": { "type": "string", "description": "The start of the key (`ak_live_`), to recognise it. The whole key is shown once, at creation." }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthly_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spent": { "type": "object", "properties": { "today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today", "month" ], "additionalProperties": false, "description": "Credits spent with this key, this UTC day and month." }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "daily_credits", "monthly_credits", "spent", "last_used_at", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "protection", "status", "capabilities", "daily_credits", "monthly_credits", "assistants", "key_count", "stats", "blocked", "urls", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "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", "keys": [ { "id": "aky_h4n8c2v6y9tk", "name": "Globex", "prefix": "ak_live_k7f2p9x4m1c8", "daily_credits": 3000, "monthly_credits": null, "spent": { "today": 60, "month": 1800 }, "last_used_at": "2026-10-29T10:00:00.000Z", "created_at": "2026-10-20T10:00:00.000Z" } ] }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "resource_not_found", "rate_limited", "internal_error" ] }, "patch": { "operationId": "updateAccess", "x-surface-coverage": { "cli": "lookio accesses update", "mcp": "update_access", "cliInputs": { "assistants": { "inputs": [ "--assistant" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Update an access", "description": "Changes the fields you send and keeps the others. `assistants` replaces the whole list. Pause it with `status: \"paused\"`: every call is refused until it is live again. Switching `protection` to `keys` needs the Pro plan; back to `public`, its keys are kept.", "tags": [ "accesses" ], "parameters": [ { "name": "access_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Update an access", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^acc_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about the access as a whole." }, "protection": { "type": "string", "enum": [ "public", "keys" ], "description": "`public`: anyone with the address may call it. `keys`: every call needs one of its access keys (Pro plan)." }, "status": { "type": "string", "enum": [ "live", "paused" ] }, "capabilities": { "type": "object", "properties": { "modes": { "type": "array", "items": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "description": "The query modes callers may ask in, at their usual prices. Empty turns answers off." }, "passages": { "type": "boolean", "description": "Whether callers may search the passages without an answer (1 credit a search)." } }, "required": [ "modes", "passages" ], "additionalProperties": false }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ], "description": "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." }, "assistants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string", "description": "What callers read about it. Its context, guidelines and resources are never shown to them." }, "reads_nothing": { "type": "boolean", "description": "It reads no searchable resource, so callers asking it are refused (for free)." } }, "required": [ "id", "name", "description", "reads_nothing" ], "additionalProperties": false } }, "key_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "stats": { "type": "object", "properties": { "today_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month_requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today_credits", "month_credits", "month_requests" ], "additionalProperties": false }, "blocked": { "anyOf": [ { "type": "string", "enum": [ "paused", "keys_need_plan", "no_keys", "no_assistants" ] }, { "type": "null" } ], "description": "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." }, "urls": { "type": "object", "properties": { "help": { "type": "string", "description": "Its help, for people and agents: what it holds and how to call it (`GET`)." }, "mcp": { "type": "string", "description": "Its MCP server (Streamable HTTP)." }, "assistants": { "type": "string" }, "ask": { "type": "string" }, "search": { "type": "string" } }, "required": [ "help", "mcp", "assistants", "ask", "search" ], "additionalProperties": false }, "keys": { "description": "Its access keys, on a single access (not in the list).", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aky_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string", "description": "Who the key is for." }, "prefix": { "type": "string", "description": "The start of the key (`ak_live_`), to recognise it. The whole key is shown once, at creation." }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthly_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spent": { "type": "object", "properties": { "today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today", "month" ], "additionalProperties": false, "description": "Credits spent with this key, this UTC day and month." }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "daily_credits", "monthly_credits", "spent", "last_used_at", "created_at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "protection", "status", "capabilities", "daily_credits", "monthly_credits", "assistants", "key_count", "stats", "blocked", "urls", "created_at", "updated_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "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": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "admin_required", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A new name, 1 to 120 characters.", "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "description": "What callers read about the access as a whole. Up to 2,000 characters.", "type": "string", "maxLength": 2000 }, "assistants": { "description": "The new full list of assistants, in order, replacing the old one: [{ id, description? }].", "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "description": { "description": "What callers read about it: what it answers, from what. Up to 1,000 characters.", "type": "string", "maxLength": 1000 } }, "required": [ "id" ] } }, "protection": { "description": "Default `public`. `keys` is on the Pro plan.", "type": "string", "enum": [ "public", "keys" ] }, "status": { "description": "`live` (default) answers; `paused` refuses every call until set live again.", "type": "string", "enum": [ "live", "paused" ] }, "modes": { "description": "The query modes callers may use, at their usual prices. Default `[\"flash\"]`; empty turns answers off (passages must then be on).", "type": "array", "items": { "type": "string", "enum": [ "eco", "flash", "deep" ] } }, "passages": { "description": "Default false.", "type": "boolean" }, "daily_credits": { "description": "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.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "monthly_credits": { "description": "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.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Only the fields you send change. `assistants` replaces the whole list." }, "examples": { "pause": { "summary": "Pause it", "value": { "status": "paused" } }, "capabilities": { "summary": "Allow Deep and passages", "value": { "modes": [ "flash", "deep" ], "passages": true } } } } } } }, "delete": { "operationId": "deleteAccess", "x-surface-coverage": { "cli": "lookio accesses delete", "mcp": "delete_access" }, "summary": "Delete an access", "description": "Deletes the access and its keys: every client stops at its next call. What it spent stays in the usage figures, its conversations in the logs. Cannot be undone; pause it to keep it.", "tags": [ "accesses" ], "parameters": [ { "name": "access_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Delete an access", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "acc_k7m3x9p2w8qr", "deleted": true }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/accesses/{access_id}/keys": { "post": { "operationId": "createAccessKey", "x-surface-coverage": { "cli": "lookio accesses keys create", "mcp": null, "mcpReason": "The key's secret is shown once and is a credential for a client: through an MCP tool it would land in the model's context and the conversation's transcript, where it outlives the moment it was needed. Admins create keys in the app, the CLI or the REST route." }, "summary": "Create an access key", "description": "A key for one client of the access, returned ONCE in `secret` (`ak_live_…`): only its hash is kept. The client sends it as `Authorization: Bearer ak_live_…`. It opens this access and nothing else; the workspace API refuses it. Optional `daily_credits` and `monthly_credits` cap this key inside the access's own ceilings. Pro plan.", "tags": [ "accesses" ], "parameters": [ { "name": "access_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "201": { "description": "Create an access key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^aky_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string", "description": "Who the key is for." }, "prefix": { "type": "string", "description": "The start of the key (`ak_live_`), to recognise it. The whole key is shown once, at creation." }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthly_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spent": { "type": "object", "properties": { "today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today", "month" ], "additionalProperties": false, "description": "Credits spent with this key, this UTC day and month." }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "daily_credits", "monthly_credits", "spent", "last_used_at", "created_at" ], "additionalProperties": false }, "secret": { "type": "string", "description": "The whole key (`ak_live_…`). Shown once: store it now and hand it to its client." } }, "required": [ "key", "secret" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "key": { "id": "aky_h4n8c2v6y9tk", "name": "Globex", "prefix": "ak_live_k7f2p9x4m1c8", "daily_credits": 3000, "monthly_credits": null, "spent": { "today": 60, "month": 1800 }, "last_used_at": "2026-10-29T10:00:00.000Z", "created_at": "2026-10-20T10:00:00.000Z" }, "secret": "ak_live_k7f2p9x4m1c8_9a3d7e1fC4b29a3d7e1fC4b29a3d7e1fC4b29a3d7e1_1f3a9c07" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "feature_not_available", "admin_required", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Who it is for, e.g. the client's name." }, "daily_credits": { "description": "Credits this key, per UTC day, inside the access's own ceilings, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "monthly_credits": { "description": "Credits this key, per UTC month, inside the access's own ceilings, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false }, "examples": { "simple": { "summary": "A key for a client, with a daily ceiling", "value": { "name": "Globex", "daily_credits": 3000 } } } } } } } }, "/v1/accesses/{access_id}/keys/{key_id}": { "patch": { "operationId": "updateAccessKey", "x-surface-coverage": { "cli": "lookio accesses keys update", "mcp": "update_access_key" }, "summary": "Update an access key", "description": "Renames the key or changes its own ceilings. Its secret never changes: to replace it, create a new key and revoke this one.", "tags": [ "accesses" ], "parameters": [ { "name": "access_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Update an access key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^aky_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string", "description": "Who the key is for." }, "prefix": { "type": "string", "description": "The start of the key (`ak_live_`), to recognise it. The whole key is shown once, at creation." }, "daily_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "monthly_credits": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "spent": { "type": "object", "properties": { "today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "month": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "today", "month" ], "additionalProperties": false, "description": "Credits spent with this key, this UTC day and month." }, "last_used_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "prefix", "daily_credits", "monthly_credits", "spent", "last_used_at", "created_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "aky_h4n8c2v6y9tk", "name": "Globex", "prefix": "ak_live_k7f2p9x4m1c8", "daily_credits": 3000, "monthly_credits": null, "spent": { "today": 60, "month": 1800 }, "last_used_at": "2026-10-29T10:00:00.000Z", "created_at": "2026-10-20T10:00:00.000Z" }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A new name: who the key is for.", "type": "string", "minLength": 1, "maxLength": 100 }, "daily_credits": { "description": "Credits this key, per UTC day, inside the access's own ceilings, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] }, "monthly_credits": { "description": "Credits this key, per UTC month, inside the access's own ceilings, may spend; null is no ceiling. A call whose price does not fit is refused with `rate_limited` until the window resets.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100000000 }, { "type": "null" } ] } }, "additionalProperties": false }, "examples": { "budget": { "summary": "A monthly ceiling", "value": { "monthly_credits": 50000 } } } } } } }, "delete": { "operationId": "deleteAccessKey", "x-surface-coverage": { "cli": "lookio accesses keys revoke", "mcp": "revoke_access_key" }, "summary": "Revoke an access key", "description": "Revokes the key: its next call answers 401 `invalid_access_key`. What it spent stays in the usage figures. Cannot be undone.", "tags": [ "accesses" ], "parameters": [ { "name": "access_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Revoke an access key", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "deleted": { "type": "boolean", "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "aky_h4n8c2v6y9tk", "deleted": true }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/assistants/{assistant_id}/publication": { "get": { "operationId": "getPublication", "x-surface-coverage": { "cli": "lookio assistants publication", "mcp": "get_publication" }, "summary": "Retrieve an assistant's publication", "description": "Whether the assistant is private, waiting for Lookio's review, public in the directory, or refused (with the reason). Admins only.", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Retrieve an assistant's publication", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "type": "string", "enum": [ "private", "pending", "public", "rejected" ], "description": "`pending`: waiting for Lookio's review. `public`: listed in the directory, any Lookio workspace may ask it. `rejected`: see `note`." }, "description": { "type": "string" }, "note": { "description": "Why Lookio refused it.", "type": [ "string", "null" ] }, "requested_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] } }, "required": [ "state", "description", "note", "requested_at", "published_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "state": "pending", "description": "Answers questions on German employment law from the statutes and the federal court's leading decisions, with citations.", "note": null, "requested_at": "2026-10-29T10:00:00.000Z", "published_at": null }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "resource_not_found", "rate_limited", "internal_error" ] }, "put": { "operationId": "publishAssistant", "x-surface-coverage": { "cli": "lookio assistants publish", "mcp": "publish_assistant" }, "summary": "Publish an assistant", "description": "Asks Lookio to list the assistant in the directory of public assistants, with this `description` (what it answers, from what, for whom). Lookio reviews every request; once approved, any Lookio workspace may ask it and pays its own credits, and you earn 20% of what others spend on it, as credits, each month. Its context, guidelines and resources stay private. While it waits for review, sending again changes the description. A public assistant keeps the description Lookio approved: to change it, unpublish it and ask again (`conflict` otherwise). Admins only.", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Publish an assistant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "type": "string", "enum": [ "private", "pending", "public", "rejected" ], "description": "`pending`: waiting for Lookio's review. `public`: listed in the directory, any Lookio workspace may ask it. `rejected`: see `note`." }, "description": { "type": "string" }, "note": { "description": "Why Lookio refused it.", "type": [ "string", "null" ] }, "requested_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] } }, "required": [ "state", "description", "note", "requested_at", "published_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "state": "pending", "description": "Answers questions on German employment law from the statutes and the federal court's leading decisions, with citations.", "note": null, "requested_at": "2026-10-29T10:00:00.000Z", "published_at": null }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "rate_limited", "internal_error" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "description": { "type": "string", "minLength": 40, "maxLength": 1000, "description": "What the directory shows: what it answers, from what kind of sources, for whom. 40 to 1,000 characters. Its context, guidelines and resources stay private." } }, "required": [ "description" ], "additionalProperties": false }, "examples": { "publish": { "summary": "Ask to publish", "value": { "description": "Answers questions on German employment law from the statutes and the federal court's leading decisions, with citations." } } } } } } }, "delete": { "operationId": "unpublishAssistant", "x-surface-coverage": { "cli": "lookio assistants unpublish", "mcp": "unpublish_assistant" }, "summary": "Unpublish an assistant", "description": "Makes it private again at once: out of the directory, and other workspaces' questions are refused. A pending request is withdrawn. Admins only.", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "admin" ] } ], "responses": { "200": { "description": "Unpublish an assistant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "state": { "type": "string", "enum": [ "private", "pending", "public", "rejected" ], "description": "`pending`: waiting for Lookio's review. `public`: listed in the directory, any Lookio workspace may ask it. `rejected`: see `note`." }, "description": { "type": "string" }, "note": { "description": "Why Lookio refused it.", "type": [ "string", "null" ] }, "requested_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] } }, "required": [ "state", "description", "note", "requested_at", "published_at" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "state": "private", "description": "Answers questions on German employment law from the statutes and the federal court's leading decisions, with citations.", "note": null, "requested_at": null, "published_at": null }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "admin_required", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/public-assistants": { "get": { "operationId": "listPublicAssistants", "x-surface-coverage": { "cli": "lookio public list", "mcp": "list_public_assistants" }, "summary": "List public assistants", "description": "The directory: assistants their workspaces published and Lookio approved, newest first. Ask any of them like your own assistants, with `POST /v1/assistants/{id}/query` (or `/search` for passages): paid by your workspace at the usual prices, the conversation kept in your workspace and its logs. `q` searches names and descriptions. Costs nothing.", "tags": [ "public-assistants" ], "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "description": "Words to find in the name or the description.", "type": "string", "maxLength": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "The `next_cursor` of the previous page, unchanged.", "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of items to return. Values outside 1-100 are clamped, and the response reports the limit actually applied." } } ], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "List public assistants", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string" }, "publisher": { "type": "string", "description": "The name of the workspace that published it." }, "published_at": { "type": [ "string", "null" ] }, "own": { "type": "boolean", "description": "It belongs to your workspace." }, "modes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "credits" ], "additionalProperties": false }, "description": "What a question costs you in each mode." } }, "required": [ "id", "name", "description", "publisher", "published_at", "own", "modes" ], "additionalProperties": false } }, "has_more": { "type": "boolean", "description": "True when another page follows: pass `next_cursor` back as `cursor`." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it back unchanged as `cursor`. Null on the last page." }, "limit": { "type": "integer", "description": "The page size actually applied." }, "request_id": { "type": "string" } }, "required": [ "data", "has_more", "next_cursor", "limit", "request_id" ] }, "examples": { "default": { "value": { "data": [ { "id": "ast_66xcnwtzj8vt", "name": "German employment law", "description": "Answers questions on German employment law from the statutes and the federal court's leading decisions, with citations.", "publisher": "Lookio", "published_at": "2026-10-29T10:00:00.000Z", "own": false, "modes": [ { "id": "eco", "credits": 10 }, { "id": "flash", "credits": 30 }, { "id": "deep", "credits": 80 } ] } ], "has_more": false, "next_cursor": null, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "invalid_parameter", "invalid_cursor", "rate_limited", "internal_error" ] } }, "/v1/public-assistants/{assistant_id}": { "get": { "operationId": "getPublicAssistant", "x-surface-coverage": { "cli": "lookio public get", "mcp": "get_public_assistant" }, "summary": "Retrieve a public assistant", "description": "One assistant of the directory: its name, description, publisher and what a question costs in each mode.", "tags": [ "public-assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } } ], "security": [ { "bearerAuth": [ "assistants:read" ] } ], "responses": { "200": { "description": "Retrieve a public assistant", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "name": { "type": "string" }, "description": { "type": "string" }, "publisher": { "type": "string", "description": "The name of the workspace that published it." }, "published_at": { "type": [ "string", "null" ] }, "own": { "type": "boolean", "description": "It belongs to your workspace." }, "modes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "eco", "flash", "deep" ] }, "credits": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "id", "credits" ], "additionalProperties": false }, "description": "What a question costs you in each mode." } }, "required": [ "id", "name", "description", "publisher", "published_at", "own", "modes" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "id": "ast_66xcnwtzj8vt", "name": "German employment law", "description": "Answers questions on German employment law from the statutes and the federal court's leading decisions, with citations.", "publisher": "Lookio", "published_at": "2026-10-29T10:00:00.000Z", "own": false, "modes": [ { "id": "eco", "credits": 10 }, { "id": "flash", "credits": 30 }, { "id": "deep", "credits": 80 } ] }, "request_id": "req_01K9X7M2Q4" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "resource_not_found", "rate_limited", "internal_error" ] } }, "/v1/assistants/{assistant_id}/search": { "post": { "operationId": "searchAssistant", "x-surface-coverage": { "cli": "lookio search", "mcp": "search_assistant", "cliInputs": { "history": { "inputs": [ "--history-file" ], "reason": "The CLI uses task-shaped names or local inputs and serializes them into this canonical REST field." } } }, "summary": "Search an assistant's passages", "description": "The passages of the assistant's resources that best match the question, best-matching document first, without an answer: for an agent or a pipeline whose own model reads them. 1 credit a search, whatever it finds; an assistant that reads no resource is refused first, for free. Same hybrid semantic and lexical search as a Flash answer (expanded to surrounding context, with the previous question included when you send `history`), so passages carry no numeric similarity score: read `text` to judge relevance. Nothing is stored. Send an `Idempotency-Key` header so a retried request is not charged twice.", "tags": [ "assistants" ], "parameters": [ { "name": "assistant_id", "in": "path", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "security": [ { "bearerAuth": [ "query" ] } ], "responses": { "200": { "description": "Search an assistant's passages", "headers": { "X-Request-Id": { "$ref": "#/components/headers/XRequestId" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assistant_id": { "type": "string", "pattern": "^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$" }, "passages": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "1-based position in the returned list, ordered from the best-matching document down." }, "title": { "type": "string" }, "text": { "type": "string", "description": "The passage, expanded to surrounding sentences or its section in document order. Passages come from hybrid semantic and lexical rank fusion, so no numeric similarity score is returned: read `text` to judge relevance." }, "section": { "type": "array", "items": { "type": "string" }, "description": "The headings above it, outermost first." }, "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "type": "string" }, "source": { "description": "The resource's source line, when it has one.", "type": "string" } }, "required": [ "n", "title", "text", "section" ], "additionalProperties": false } }, "credit_cost": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Credits this search cost: 1." } }, "required": [ "assistant_id", "passages", "credit_cost" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "data", "request_id" ] }, "examples": { "default": { "value": { "data": { "assistant_id": "ast_66xcnwtzj8vt", "passages": [ { "n": 1, "title": "Refund policy", "text": "You can return an item within 30 days of delivery.", "section": [ "Returns" ], "url": "https://docs.acme.com/refunds" } ], "credit_cost": 1 }, "request_id": "req_01K9X7M2Q4" } } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-error-codes": [ "authentication_required", "invalid_api_key", "api_key_expired", "api_key_revoked", "insufficient_scope", "permission_denied", "invalid_request", "unknown_field", "invalid_parameter", "request_too_large", "resource_not_found", "conflict", "assistant_has_no_resources", "insufficient_credits", "rate_limited", "internal_error", "service_unavailable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "What to search for, in any language." }, "history": { "description": "The previous turns of your conversation, oldest first: the last question is searched with this one, so a follow-up (\"and for Germany?\") finds the right passages.", "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string", "maxLength": 12000 } }, "required": [ "role", "content" ] } }, "limit": { "description": "How many passages, 1 to 20 (default 8).", "type": "integer", "minimum": 1, "maximum": 20 } }, "required": [ "question" ], "additionalProperties": false }, "examples": { "simple": { "summary": "A search", "value": { "question": "refund window", "limit": 5 } } } } } } } } } }