Skip to content
KataraKatara documentation

Assemble the passages that answer a query within a model's token budget

POST
/katara/v1/orgs/{org_id}/environments/{environment_id}/context:assemble
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/context:assemble \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "query": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example", "media_type": "text/plain", "size_bytes": 1 }, "collections": [ { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expected_revision": 1 } ], "model_id": "example", "token_budget": 1, "per_collection": 1, "grant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "budget_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Requires memory read access to each collection and a grant and budget that fund the query. Searches each named collection at the revision the caller read, embedding the stored query once per collection and paying for it, then packs the best passages across them into token_budget as the model counts them. Every passage names its source, its collection and its chunk; over_budget counts the passages left out. Repeating a request with the same id is the same paid searches. Nothing returned is content the caller could not read through the collection.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Header Parameters

Section titled “Header Parameters”
X-Katara-CSRF
Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A stored query, the collections to search at the revisions read, the model and budget to pack for, and what funds the search.

object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
query
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
collections
required
Array<object>
>= 1 items <= 5 items unique items
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
expected_revision
required
integer
>= 1 <= 9007199254740991
model_id
required
string
>= 1 characters <= 200 characters
token_budget
required
integer
>= 1 <= 1000000
per_collection
required
integer
>= 1 <= 25
grant_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
budget_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000

Responses

Section titled “Responses”

200

Section titled “200”

Successful request

Media typeapplication/json
object
data
required
Array<object>
<= 125 items

One passage and where it came from. tokens is the estimate for the requested model, which is what the budget counts.

object
collection_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
source
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
result
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
chunk

Where in the source the passage was cut.

object
score
required
number
text
required
string
<= 65536 characters
tokens
required
integer
<= 1000000
token_budget
required
integer
>= 1 <= 1000000
tokens
required
integer
<= 1000000
candidates
required
integer
<= 125
over_budget
required
integer
<= 125
Example
{
  "data": [
    {
      "source": {
        "media_type": "text/plain"
      },
      "result": {
        "media_type": "text/plain"
      }
    }
  ]
}

409

Section titled “409”

Account_changed: reload and review with the signed-in account.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
snapshot_ref
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
Example
{
  "error": {
    "action": "sign_in"
  }
}