Trellis Data Logo
Developers Doc

Knowledge Base API

Sample requests and responses for building with the Agentaus API.

Reference for creating and managing datasets and instances (documents) programmatically — e.g. from a backend job, not through the Agentaus UI. This is a distinct, stable contract from the APIs the UI itself uses: a small set of fields and a single JSON error envelope.

Resources

Dataset object

id
Typestring (uuid)
NotesUse this in all subsequent calls
object
Typestring
NotesAlways "dataset"
name
Typestring
NotesDisplay name for the dataset
description
Typestring | null
NotesFree-text description of the dataset's contents
data_type
Typestring
NotesAlways "document" for datasets created through this API
status
Typestring
Notes"ready" if completed_instances >= total_instances (including an empty dataset), otherwise "processing"
total_instances
Typeinteger
NotesInstance count
completed_instances
Typeinteger
NotesInstances that have finished vectorisation
created_at / updated_at
Typestring
NotesISO 8601, UTC
json
{
  "id": "5a1f7e2c-...",
  "object": "dataset",
  "name": "Support KB",
  "description": "Internal support articles",
  "data_type": "document",
  "status": "processing",
  "total_instances": 12,
  "completed_instances": 9,
  "created_at": "2026-09-01T02:15:30Z",
  "updated_at": "2026-09-10T11:02:00Z"
}

Instance object

An instance is one uploaded document inside a dataset.
id
Typestring (uuid)
NotesUse this in subsequent retrieve/update/delete calls
object
Typestring
NotesAlways "instance"
dataset_id
Typestring (uuid)
NotesParent dataset
filename
Typestring | null
NotesOriginal uploaded filename
external_id
Typestring | null
NotesYour own identifier for this document (max 255 chars); settable and updatable
status
Typestring
NotesOne of "pending", "processing", "completed", or "failed", reflecting document-processing progress
error
Typestring | null
NotesPresent only when status is "failed"
content_type
Typestring | null
NotesDerived from the filename extension
created_at / updated_at
Typestring
NotesISO 8601, UTC
json
{
  "id": "9c3d1a44-...",
  "object": "instance",
  "dataset_id": "5a1f7e2c-...",
  "filename": "handbook.pdf",
  "external_id": "kb-042",
  "status": "pending",
  "content_type": "application/pdf",
  "created_at": "2026-09-10T11:00:00Z",
  "updated_at": "2026-09-10T11:00:00Z"
}

Datasets

Create a dataset

POST
/api/v1/datasets

Create a Dataset

Requires headers Authorization: Bearer <token> and Content-Type: application/json.
Body parameters
name
Required
string
Display name for the dataset.
description
Optional
string
Free-text description of the dataset's contents.
curl -X POST https://<host>/api/v1/datasets \
  -H "Authorization: Bearer $AGENTAUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support KB",
    "description": "Internal support articles"
  }'
Response
{
  "id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
  "object": "dataset",
  "name": "Support KB",
  "description": "Internal support articles",
  "data_type": "document",
  "status": "ready",
  "total_instances": 0,
  "completed_instances": 0,
  "created_at": "2026-09-10T11:00:00Z",
  "updated_at": "2026-09-10T11:00:00Z"
}

See Errors for the full list of error codes.

Retrieve a dataset

GET
/api/v1/datasets/{id}

Retrieve a Dataset

Requires header Authorization: Bearer <token>.
Path parameters
id
Required
string (uuid)
Dataset id
curl https://<host>/api/v1/datasets/$DATASET_ID \
  -H "Authorization: Bearer $AGENTAUS_API_KEY"
Response
{
  "id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
  "object": "dataset",
  "name": "Support KB",
  "description": "Internal support articles",
  "data_type": "document",
  "status": "processing",
  "total_instances": 12,
  "completed_instances": 9,
  "created_at": "2026-09-01T02:15:30Z",
  "updated_at": "2026-09-10T11:02:00Z"
}

See Errors for the full list of error codes.

Update a dataset

PATCH
/api/v1/datasets/{id}

Update a Dataset

Requires headers Authorization: Bearer <token> and Content-Type: application/json. Only name/description are accepted — any other key is rejected. Fields you omit are left unchanged.
Path parameters
id
Required
string (uuid)
Dataset id
Body parameters
name
Optional
string
New display name for the dataset.
description
Optional
string
New free-text description of the dataset's contents.
curl -X PATCH https://<host>/api/v1/datasets/$DATASET_ID \
  -H "Authorization: Bearer $AGENTAUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'
Response
{
  "id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
  "object": "dataset",
  "name": "Support KB",
  "description": "Updated description",
  "data_type": "document",
  "status": "processing",
  "total_instances": 12,
  "completed_instances": 9,
  "created_at": "2026-09-01T02:15:30Z",
  "updated_at": "2026-09-10T11:05:00Z"
}

See Errors for the full list of error codes.

Delete a dataset

DELETE
/api/v1/datasets/{id}

Delete a Dataset

Requires header Authorization: Bearer <token>. Revokes access and queues record/media/vector cleanup asynchronously — a 200 response means the dataset is gone, not that every downstream artifact has finished being purged.
Path parameters
id
Required
string (uuid)
Dataset id
curl -X DELETE https://<host>/api/v1/datasets/$DATASET_ID \
  -H "Authorization: Bearer $AGENTAUS_API_KEY"
Response
{
  "id": "5a1f7e2c-...",
  "object": "dataset",
  "deleted": true
}

See Errors for the full list of error codes.

Get dataset stats

GET
/api/v1/datasets/{dataset_id}/stats

Get Dataset Stats

Requires header Authorization: Bearer <token>. Use this endpoint to poll for completion.
Path parameters
dataset_id
Required
string (uuid)
Dataset id
curl https://<host>/api/v1/datasets/$DATASET_ID/stats \
  -H "Authorization: Bearer $AGENTAUS_API_KEY"
Response
{
  "total_instances": 12,
  "ready": 9,
  "processing": 3,
  "failed": 0
}

See Errors for the full list of error codes.

Instances

Create an instance (upload a document)

POST
/api/v1/datasets/{dataset_id}/instances

Create an Instance

Requires header Authorization: Bearer <token> and a multipart/form-data body — exactly one file per request. Uploading queues document parsing/vectorisation asynchronously.
Path parameters
dataset_id
Required
string (uuid)
Parent dataset id
Body parameters
file
Required
file
One of .docx .pdf .doc .ppt .pptx .xls .xlsx .epub .html .md .odt .org .rst .rtf .csv .tsv .xml .txt .js .jsx .css .py .sql .ts .tsx .sh .java .cs .c .cpp .php .ps1 .go .rs .kt .lua .dart .asm .rb .jpg .jpeg .png .webp .bmp, up to 100,000,000 bytes (100 MB)
external_id
Optional
string
Your own id for the document, max 255 chars
curl -X POST https://<host>/api/v1/datasets/$DATASET_ID/instances \
  -H "Authorization: Bearer $AGENTAUS_API_KEY" \
  -F "[email protected]" \
  -F "external_id=kb-042"
Response
{
  "id": "9c3d1a44-6b21-4f2e-8a13-2d5e7f8b9c10",
  "object": "instance",
  "dataset_id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
  "filename": "handbook.pdf",
  "external_id": "kb-042",
  "status": "pending",
  "content_type": "application/pdf",
  "created_at": "2026-09-10T11:00:00Z",
  "updated_at": "2026-09-10T11:00:00Z"
}

See Errors for the full list of error codes.

Retrieve an instance

GET
/api/v1/datasets/{dataset_id}/instances/{id}

Retrieve an Instance

Requires header Authorization: Bearer <token>.
Path parameters
dataset_id
Required
string (uuid)
Parent dataset id
id
Required
string (uuid)
Instance id
curl https://<host>/api/v1/datasets/$DATASET_ID/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $AGENTAUS_API_KEY"
Response
{
  "id": "9c3d1a44-6b21-4f2e-8a13-2d5e7f8b9c10",
  "object": "instance",
  "dataset_id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
  "filename": "handbook.pdf",
  "external_id": "kb-042",
  "status": "pending",
  "content_type": "application/pdf",
  "created_at": "2026-09-10T11:00:00Z",
  "updated_at": "2026-09-10T11:00:00Z"
}

See Errors for the full list of error codes.

Update an instance

PATCH
/api/v1/datasets/{dataset_id}/instances/{id}

Update an Instance

Requires headers Authorization: Bearer <token> and Content-Type: application/json. Only external_id is accepted — any other key is rejected.
Path parameters
dataset_id
Required
string (uuid)
Parent dataset id
id
Required
string (uuid)
Instance id
Body parameters
external_id
Optional
string
Max 255 chars
curl -X PATCH https://<host>/api/v1/datasets/$DATASET_ID/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $AGENTAUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_id": "kb-042-v2"}'
Response
{
  "id": "9c3d1a44-6b21-4f2e-8a13-2d5e7f8b9c10",
  "object": "instance",
  "dataset_id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
  "filename": "handbook.pdf",
  "external_id": "kb-042-v2",
  "status": "pending",
  "content_type": "application/pdf",
  "created_at": "2026-09-10T11:00:00Z",
  "updated_at": "2026-09-10T11:06:00Z"
}

See Errors for the full list of error codes.

Delete an instance

DELETE
/api/v1/datasets/{dataset_id}/instances/{id}

Delete an Instance

Requires header Authorization: Bearer <token>. Database rows are removed synchronously; S3 file and vector-store cleanup are best-effort and asynchronous.
Path parameters
dataset_id
Required
string (uuid)
Parent dataset id
id
Required
string (uuid)
Instance id
curl -X DELETE https://<host>/api/v1/datasets/$DATASET_ID/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $AGENTAUS_API_KEY"
Response
{
  "id": "9c3d1a44-...",
  "object": "instance",
  "deleted": true
}

Note the response key here is uuid, not id as on every other instance response — match on whichever field you sent in the request if you need to confirm which instance was deleted.

See Errors for the full list of error codes.

Errors

All errors — including authentication failures before your request reaches a specific dataset or instance — use this envelope. request_id echoes the X-Request-Id response header when present — include it when reporting an issue:
json
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_parameter",
    "message": "name is required",
    "param": "name",
    "request_id": "b3f0b1b2-1111-4444-8888-abcdefabcdef"
  }
}
400
Bad Request
codemissing_required_parameter
MeaningA required field was omitted
400
Bad Request
codeinvalid_parameter_value
MeaningA field failed validation (bad enum, wrong type, etc.)
400
Bad Request
codeparameter_too_long
MeaningA field exceeded its max length
400
Bad Request
codeunsupported_parameter
MeaningAn update request included a field it doesn't accept
400
Bad Request
codetoo_many_files
MeaningMore than one file uploaded to an instance create
400
Bad Request
codeunsupported_file_type
MeaningFile extension not in the allowed list
400
Bad Request
codefile_too_large
MeaningFile exceeds 100,000,000 bytes (100 MB)
400
Bad Request
codeinvalid_id
MeaningThe dataset/instance id in the URL isn't a well-formed UUID
401
Unauthorized
codeunauthorized
MeaningMissing, invalid, or expired bearer token
403
Forbidden
codeinsufficient_permissions
MeaningYour account has no base access to this API
404
Not Found
codedataset_not_found
MeaningDataset doesn't exist, or you lack access to it
404
Not Found
codeinstance_not_found
MeaningInstance doesn't exist in that dataset, or you lack access
500
Internal Server Error
codeinternal_error
MeaningUnexpected server error
503
Service Unavailable
codeservice_unavailable
MeaningAuthorization backend temporarily unavailable — retry

Asynchronous processing

Uploading a document only queues parsing and vectorisation — it doesn't happen inline with the request. To know when a document is usable:
  • Poll GET /datasets/{id}/stats or GET /datasets/{id} and wait for completed_instances == total_instances / status == "ready".
  • The per-instance status field starts at "pending" and is not currently a reliable per-instance completion signal — prefer the dataset-level aggregate above to decide when a dataset is ready to query.
End-to-end example — create a dataset, upload a document, poll until ready, then clean up:
bash
TOKEN="..."
HOST="https://<host>"

DATASET_ID=$(curl -s -X POST "$HOST/api/v1/datasets" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Support KB"}' | jq -r .id)

curl -s -X POST "$HOST/api/v1/datasets/$DATASET_ID/instances" \
  -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]" -F "external_id=kb-042"

until [ "$(curl -s "$HOST/api/v1/datasets/$DATASET_ID" -H "Authorization: Bearer $TOKEN" | jq -r .status)" = "ready" ]; do
  sleep 5
done

curl -s -X DELETE "$HOST/api/v1/datasets/$DATASET_ID" \
  -H "Authorization: Bearer $TOKEN"

Using a dataset in Chat Completions

Once a dataset's status is ready (see above), ground a Chat Completions response in it by adding an agentaus_dataset_search tool entry with the dataset's id to tools — no other change to the request is needed:
sh
curl -X POST https://<host>/api/v1/chat/completions \
  -H "Authorization: Bearer $AGENTAUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "What is our policy on late refunds?"}],
    "stream": false,
    "tools": [
      {
        "type": "agentaus_dataset_search",
        "dataset_ids": ["5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10"]
      }
    ]
  }'
Retrieval runs server-side before inference starts, so a normal text completion comes back — no tool call round-trip to handle:
json
{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "According to the Support KB, late refunds are approved case-by-case within 14 days of the original purchase — see the \"Refunds\" section of the handbook for the full policy.",
        "refusal": null,
        "role": "assistant",
        "tool_calls": []
      }
    }
  ],
  "created": 1782460000,
  "id": "chatcmpl-1782460000",
  "model": "agentaus",
  "object": "chat.completion",
  "usage": {
    "input_tokens": 3120,
    "output_tokens": 48
  }
}
See agentaus_dataset_search on the Chat Completions API page for the full tool contract — combining it with your own function tools, the dataset_ids field, and its error cases.

Agents & Harnesses

Configure OpenCode to use the Agentaus API as its model provider.

On this page

ResourcesDataset objectInstance objectDatasetsCreate a datasetRetrieve a datasetUpdate a datasetDelete a datasetGet dataset statsInstancesCreate an instance (upload a document)Retrieve an instanceUpdate an instanceDelete an instanceErrorsAsynchronous processingUsing a dataset in Chat Completions