---
title: "Call an access"
description: "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."
canonical: "https://lookio.app/docs/developers/accesses"
updated: "2026-11-08"
---

# Call an access

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](/docs/guides/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.

**Your code (JSON)**

```bash
curl https://api.lookio.app/a/acc_be4kjcvee2kf
```

```json
{
  "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_…"
}
```

**An AI agent (Markdown)**

```bash
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 browser**

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

```bash
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?"}'
```

```json
{
  "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_…"
}
```

**`question`** (`string`, required)

The question, 1 to 4,000 characters.

**`assistant_id`** (`string`)

Which assistant answers. Optional when the access has only one.

**`mode`** (`string`)

`eco`, `flash` or `deep`, among the modes the access allows. Without it, the access's default mode.

**`history`** (`array`)

The 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.

```bash
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.

```bash title="Claude Code"
claude mcp add --transport http billowfin https://mcp.lookio.app/a/acc_be4kjcvee2kf/mcp \
  --header "Authorization: Bearer ak_live_…"
```

```json title="Cursor, Claude Desktop"
{
  "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](/docs/developers/rate-limits#accesses).

## Errors

Errors have the usual API format: `{ "error": { "code", "message", "param"? } }`. See [Errors](/docs/developers/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.                                                                   |