assistants

Ask an assistant a question

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

POST/v1/assistants/{assistant_id}/query

Request

curl --request POST \
  --url 'https://api.lookio.app/v1/assistants/<assistant_id>/query' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "question": "<string>"
}'

import json
import requests

url = "https://api.lookio.app/v1/assistants/<assistant_id>/query"
headers = {
  "Authorization": "<api-key>",
  "Content-Type": "application/json"
}
payload = json.loads("{\"question\":\"<string>\"}")

response = requests.request("POST", url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.lookio.app/v1/assistants/<assistant_id>/query", {
  method: "POST",
  headers: {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "question": "<string>"
  }),
});

const data = await response.json();
console.log(data);

<?php
$client = curl_init();

curl_setopt($client, CURLOPT_URL, "https://api.lookio.app/v1/assistants/<assistant_id>/query");
curl_setopt($client, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($client, CURLOPT_HTTPHEADER, [
    "Authorization: <api-key>",
    "Content-Type: application/json",
]);
curl_setopt($client, CURLOPT_POSTFIELDS, "{\"question\":\"<string>\"}");
curl_setopt($client, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($client);
curl_close($client);
echo $response;

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  req, _ := http.NewRequest("POST", "https://api.lookio.app/v1/assistants/<assistant_id>/query", bytes.NewBuffer([]byte("{\"question\":\"<string>\"}")))
  req.Header.Set("Authorization", "<api-key>")
  req.Header.Set("Content-Type", "application/json")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  data, _ := io.ReadAll(res.Body)
  fmt.Println(string(data))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var request = HttpRequest.newBuilder(URI.create("https://api.lookio.app/v1/assistants/<assistant_id>/query"))
    .header("Authorization", "<api-key>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"question\":\"<string>\"}"))
    .build();

var response = HttpClient.newHttpClient().send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

require 'net/http'
require 'json'

uri = URI("https://api.lookio.app/v1/assistants/<assistant_id>/query")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "<api-key>"
request["Content-Type"] = "application/json"
request.body = "{\"question\":\"<string>\"}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end

puts response.body

application/json

{
  "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"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "param": "<string>",
    "docs_url": "<string>",
    "action_url": "<string>"
  },
  "request_id": "<string>"
}

Requires query.

This is the only call that spends credits. The cost depends on mode:

`mode`	Credits
`eco`	10
`flash` (default)	30
`deep`	80

The price is fixed, whatever the length of the answer. An answer that finds nothing, or a greeting, costs the same: every question the model works on is charged. The only refusal that costs nothing is assistant_has_no_resources (409): the assistant reads no resource, so nothing is sent to a model and no credit is held. Connect resources to the assistant, then ask again. See Core concepts.

Lookio holds the price of the mode before it starts. If the balance cannot cover the hold, the call fails with insufficient_credits, and the error carries a link to the pricing page in action_url.

Conversations. Every answer is kept in a conversation, for a person and for an API key. The response carries conversation_id and, for an API key, the answer’s message_id. Send the next question with that conversation_id and Lookio reads the history itself. A conversation stays with its assistant and, for an API key, with the key that started it. Sending conversation_id with history fails with invalid_request: history is for when you keep the conversation yourself (up to 20 turns, the last 6 are used).

End users and storage (API keys). Send end_user, your own id for the person asking, to group that person’s conversations: a conversation can then only be continued, read or deleted with the same end_user. Send store: false to keep nothing: no conversation and no log, and conversation_id and message_id come back null. A kept conversation is readable in the workspace’s logs and deleted 90 days after its last message. A person’s connection that sends end_user or store gets invalid_parameter. See Conversations and end users.

Streaming. Set stream to true to receive server-sent events instead of JSON. See Streaming.

Retries. Send an Idempotency-Key so a retried JSON request is not charged twice. A stream is not replayed: do not retry one blindly. See Idempotency.

The assistant answers only from resources that are ready. When the sources hold no answer, it says so and charges the same price for that question.

Authorizations

Authorizationbearerin headerrequired

Path parameters

assistant_idstringrequiredpattern: ^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$

Header parameters

Idempotency-Keystringlength: 1–255 chars

A unique key for this request, such as a UUID, 1 to 255 visible ASCII characters. Send the same key when you retry: the first response is returned (with Idempotent-Replayed: true) instead of running the request again, for 24 hours, per credential. The same key on a different request is a 409 conflict. A streamed answer is not recorded.

Body

application/jsonrequired

questionstringrequiredlength: 1–12000 chars

conversation_idstringpattern: ^(?:res|doc|ver|ast|wdg|cnv|msg|att|acc|aky)_[abcdefghjkmnpqrstuvwxyz23456789]{12}$

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.

historyobject[]items: ≤ 20 items

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.

Show child attributes

history.roleenum<string>requiredone of: user, assistant

history.contentstringrequiredlength: ≤ 12000 chars

end_userstringpattern: ^[\w.@:+\-]{1,200}$

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.

storeboolean

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.

modeenum<string>default: flashone of: eco, flash, deep

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.

streambooleandefault: false

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.

Response

application/json

Ask an assistant a question

dataobjectrequired

Show child attributes

data.answerstringrequired

Markdown. Citations appear as [1], [2]…

data.citationsobject[]required

Show child attributes

data.citations.resource_idstringrequired

The cited resource. Empty for a public assistant of another workspace: its resources stay its own.

data.citations.titlestringrequired

data.citations.textstringrequired

The passage the answer relies on.

data.citations.ninteger

The number the answer cites it by, as [1].

data.citations.sectionstring[]

data.citations.pageinteger

data.citations.urlstring

data.citations.sourcestring

The cited resource's source, when it has one.

data.conversation_idstringnullrequired

The conversation this answer belongs to: pass it back as conversation_id to continue it. Null when nothing was stored (store: false).

data.message_idstringnullrequired

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.

data.credit_costintegerrequired

Credits this answer cost. A model answer costs its mode's fixed price.

data.credits_remaininginteger | nullrequired

data.simulatedbooleanrequired

True on a development deployment answering without a model.

request_idstringrequired

Ask an assistant a question

Authorizations

Path parameters

Header parameters

Body

Response

Use these docs with your AI tools

Query these docs via MCP

Query these docs over HTTP

Read these docs as Markdown