Call an access
Ask the assistants someone shared with you through a Lookio access, from your code over HTTP or from an AI client over MCP. No Lookio account needed.
Someone gave you an access address, such as https://api.lookio.app/a/acc_be4kjcvee2kf. You can ask some of their assistants. You need no Lookio account. Their workspace pays for your questions.
To create an access, see Accesses.
What you can call
| Method and path | What it does | Cost |
|---|---|---|
GET /a/{access_id} | Describes the access: its assistants, what you may do, the prices, the addresses. | Free |
GET /a/{access_id}/assistants | Lists its assistants with their ids and descriptions. | Free |
POST /a/{access_id}/ask | Asks an assistant. Returns an answer with citations. | The mode’s price, paid by the owner |
POST /a/{access_id}/search | Returns the best passages, without an answer, when the owner allows it. | 1 credit, paid by the owner |
POST /a/{access_id}/mcp | The same, as an MCP server (Streamable HTTP, stateless). | As above |
All paths start at https://api.lookio.app. The MCP server also answers at https://mcp.lookio.app/a/{access_id}/mcp.
Start with the address itself
GET on the address describes the access. The format depends on the client.
curl https://api.lookio.app/a/acc_be4kjcvee2kf{
"data": {
"id": "acc_be4kjcvee2kf",
"name": "Partner integrations",
"protection": "keys",
"assistants": [
{ "id": "ast_kw9tvh2ze2ar", "name": "Support assistant", "description": "How to use Billowfin: invoices, payments, taxes, account." }
],
"capabilities": { "modes": ["flash", "deep"], "passages": true },
"prices": [{ "id": "flash", "label": "Flash answer", "credits": 30 }],
"urls": { "ask": "https://api.lookio.app/a/acc_be4kjcvee2kf/ask", "mcp": "https://mcp.lookio.app/a/acc_be4kjcvee2kf/mcp" },
"authentication": "Authorization: Bearer ak_live_…"
},
"request_id": "req_…"
}curl https://api.lookio.app/a/acc_be4kjcvee2kf -H "Accept: text/markdown"The same facts as a short guide for an agent: the assistants, what it may do, the MCP setup, the HTTP calls with an example, and the errors. ?format=md gives the same.
A simple page with the same guide.
An access is open to anyone with the address, or protected by keys. For a protected access, the owner gives you a key. Without a key, the address shows only its name and how to get a key.
Ask a question
curl https://api.lookio.app/a/acc_be4kjcvee2kf/ask \
-H "Authorization: Bearer $LOOKIO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"assistant_id": "ast_kw9tvh2ze2ar", "question": "How do I issue a credit note?"}'{
"data": {
"assistant_id": "ast_kw9tvh2ze2ar",
"answer": "Open the paid invoice, then choose More > Create credit note [1]. …",
"citations": [
{ "n": 1, "title": "Issue a credit note", "section": ["Issue a credit note", "From a paid invoice"], "text": "Open the invoice, select More, then Create credit note. …", "url": "https://help.billowfin.com/invoices/credit-notes" }
],
"mode": "flash",
"credit_cost": 30
},
"request_id": "req_…"
}questionstringrequiredThe question, 1 to 4,000 characters.
assistant_idstringWhich assistant answers. Optional when the access has only one.
modestringeco, flash or deep, among the modes the access allows. Without it, the access’s default mode.
historyarrayThe previous messages, oldest first, as { "role": "user" | "assistant", "content": "…" }. Up to 20. Lookio uses the last 6. An access keeps no conversation, so send the history for a follow-up.
Send an Idempotency-Key header, and the same value on a retry. Lookio then charges the question once.
Search the passages
If the owner turns on passage search, POST /search returns the best passages without an answer, for 1 credit. Your own model writes the answer.
curl https://api.lookio.app/a/acc_be4kjcvee2kf/search \
-H "Authorization: Bearer $LOOKIO_ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"question": "credit notes", "limit": 5}'It takes question, assistant_id, history, and limit (1 to 20). It returns passages, in the same shape as citations.
From an AI client (MCP)
Add the MCP address to your client. With a key, send it as a header.
claude mcp add --transport http billowfin https://mcp.lookio.app/a/acc_be4kjcvee2kf/mcp \
--header "Authorization: Bearer ak_live_…"{
"mcpServers": {
"billowfin": {
"url": "https://mcp.lookio.app/a/acc_be4kjcvee2kf/mcp",
"headers": { "Authorization": "Bearer ak_live_…" }
}
}
}The server has up to three tools, as the access allows: list_assistants, ask and search_passages. Claude.ai and ChatGPT cannot send a header, so they reach public accesses only.
Limits
Each caller can send 60 requests per minute. A caller is one access key, or one IP address on a public access. All callers together can send 600 requests per minute. Responses send RateLimit-Policy: 60;w=60. Past a limit, the answer is 429 with Retry-After. See Rate limits.
Errors
Errors have the usual API format: { "error": { "code", "message", "param"? } }. See Errors.
| Code | Meaning |
|---|---|
invalid_access_key | The key is missing, wrong or revoked. Ask the owner for a key. |
invalid_parameter | A field is wrong, or assistant_id is missing on an access with several assistants. The message lists the valid ids. |
feature_not_available | The mode or the passage search is off on this access. The message says what is allowed. |
resource_not_found | No access, or no such assistant on it. |
rate_limited | Too many calls, or the access or your key reached a daily or monthly credit ceiling. The message says which. Wait the seconds in Retry-After. |
service_unavailable | The access cannot answer now: it is paused, or the owner has no credits left. |