assistants

Search an assistant's passages

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.

POST/v1/assistants/{assistant_id}/search

Request

curl --request POST \
  --url 'https://api.lookio.app/v1/assistants/<assistant_id>/search' \
  --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>/search"
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>/search", {
  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>/search");
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>/search", 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>/search"))
    .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>/search")
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": {
    "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"
}

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

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–4000 chars

What to search for, in any language.

historyobject[]items: ≤ 20 items

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.

Show child attributes

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

history.contentstringrequiredlength: ≤ 12000 chars

limitintegerrange: 1–20

How many passages, 1 to 20 (default 8).

Response

application/json

Search an assistant's passages

dataobjectrequired

Show child attributes

data.assistant_idstringrequiredpattern: ^ast_[abcdefghjkmnpqrstuvwxyz23456789]{12}$

data.passagesobject[]required

Show child attributes

data.passages.nintegerrequired

1-based position in the returned list, ordered from the best-matching document down.

data.passages.titlestringrequired

data.passages.textstringrequired

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.

data.passages.sectionstring[]required

The headings above it, outermost first.

data.passages.pageinteger

data.passages.urlstring

data.passages.sourcestring

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

data.credit_costintegerrequired

Credits this search cost: 1.

request_idstringrequired

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

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

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

Search an assistant's passages

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