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

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

Field	Type	Notes
id	string (uuid)	Use this in all subsequent calls
object	string	Always `"dataset"`
name	string	Display name for the dataset
description	string \| null	Free-text description of the dataset's contents
data_type	string	Always `"document"` for datasets created through this API
status	string	`"ready"` if `completed_instances >= total_instances` (including an empty dataset), otherwise `"processing"`
total_instances	integer	Instance count
completed_instances	integer	Instances that have finished vectorisation
created_at / updated_at	string	ISO 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.

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

Field	Type	Notes
id	string (uuid)	Use this in subsequent retrieve/update/delete calls
object	string	Always `"instance"`
dataset_id	string (uuid)	Parent dataset
filename	string \| null	Original uploaded filename
external_id	string \| null	Your own identifier for this document (max 255 chars); settable and updatable
status	string	One of `"pending"`, `"processing"`, `"completed"`, or `"failed"`, reflecting document-processing progress
error	string \| null	Present only when `status` is `"failed"`
content_type	string \| null	Derived from the filename extension
created_at / updated_at	string	ISO 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.

List datasets

GET

/api/v1/datasets

List Datasets

Requires header Authorization: Bearer <token>. Returns the datasets you own in your tenant, one page at a time. Each item in data is a dataset object.

Query parameters

count

Optional

integer

Page size, 1–100. Defaults to 20.

sort_by

Optional

string

inserted_at (default) or name.

sort_order

Optional

string

desc (default) or asc.

cursor

Optional

string

The cursor from the previous response, to fetch the next page.

is_usable

Optional

boolean

true or false to return only usable or only unusable datasets. Omit to list both.

curl -G https://<host>/api/v1/datasets \
  -H "Authorization: Bearer $AGENTAUS_API_KEY" \
  -d count=2 \
  -d sort_by=name \
  -d sort_order=asc

Response

{
  "object": "dataset.list",
  "data": [
    {
      "id": "1d7b9e40-6a2c-4f13-8e5d-3c9a7b2f0e61",
      "object": "dataset",
      "name": "Product FAQ",
      "description": null,
      "data_type": "document",
      "status": "ready",
      "total_instances": 4,
      "completed_instances": 4,
      "created_at": "2026-08-20T08:30:00Z",
      "updated_at": "2026-08-21T09:12:45Z"
    },
    {
      "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"
    }
  ],
  "cursor": "g3QAAAABZAAEbmFtZW0AAAAKU3VwcG9ydCBLQg",
  "has_next_page": true
}

The response is a list envelope:

object

Typestring

NotesAlways "dataset.list"

data

Typearray

NotesThe datasets on this page, as dataset objects

cursor

Typestring | null

NotesPass this as the cursor query param to fetch the next page

has_next_page

Typeboolean

Notesfalse once you've reached the last page

Field	Type	Notes
object	string	Always `"dataset.list"`
data	array	The datasets on this page, as dataset objects
cursor	string \| null	Pass this as the `cursor` query param to fetch the next page
has_next_page	boolean	`false` once you've reached the last page

To page through every dataset, repeat the request with the returned cursor until has_next_page is false. Keep sort_by and sort_order the same while following a cursor. A malformed or stale cursor is rejected with a 400Bad Request.

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

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

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

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.

List instances

GET

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

List Instances

Requires header Authorization: Bearer <token>. Returns the instances in a dataset, one page at a time, ordered by creation time. Each item in data is an instance object.

Path parameters

dataset_id

Required

string (uuid)

Parent dataset id

Query parameters

status

Optional

array of strings

Only return instances in these statuses — any of pending, processing, completed, failed. Repeat the param for each value, e.g. status[]=pending&status[]=failed. Omit to list all.

count

Optional

integer

Page size, 1–100. Defaults to 20.

order

Optional

string

desc (default, newest first) or asc, by creation time.

cursor

Optional

string

The cursor from the previous response, to fetch the next page.

curl -G https://<host>/api/v1/datasets/$DATASET_ID/instances \
  -H "Authorization: Bearer $AGENTAUS_API_KEY" \
  -d count=2 \
  -d order=asc \
  --data-urlencode "status[]=completed" \
  --data-urlencode "status[]=failed"

Response

{
  "object": "instance.list",
  "data": [
    {
      "id": "9c3d1a44-6b21-4f2e-8a13-2d5e7f8b9c10",
      "object": "instance",
      "dataset_id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
      "filename": "handbook.pdf",
      "external_id": "kb-042",
      "status": "completed",
      "content_type": "application/pdf",
      "created_at": "2026-09-10T11:00:00Z",
      "updated_at": "2026-09-10T11:03:20Z"
    },
    {
      "id": "e4a8c2f1-0d3b-4c7e-9a56-7b1f2e3d4c58",
      "object": "instance",
      "dataset_id": "5a1f7e2c-3b4d-4e21-9f2a-8b6d2a5c9e10",
      "filename": "pricing.xlsx",
      "external_id": null,
      "status": "failed",
      "error": "Unable to parse document",
      "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "created_at": "2026-09-10T11:01:00Z",
      "updated_at": "2026-09-10T11:01:45Z"
    }
  ],
  "cursor": "g3QAAAACZAACaWRtAAAAJGU0YThjMmYx",
  "has_next_page": true
}

The response is a list envelope:

object

Typestring

NotesAlways "instance.list"

data

Typearray

NotesThe instances on this page, as instance objects

cursor

Typestring | null

NotesPass this as the cursor query param to fetch the next page

has_next_page

Typeboolean

Notesfalse once you've reached the last page

Field	Type	Notes
object	string	Always `"instance.list"`
data	array	The instances on this page, as instance objects
cursor	string \| null	Pass this as the `cursor` query param to fetch the next page
has_next_page	boolean	`false` once you've reached the last page

To page through every instance, repeat the request with the returned cursor until has_next_page is false. Keep order the same while following a cursor. An invalid query param value, including a malformed cursor, is rejected with a 400Bad Request invalid_parameter_value.

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

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

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

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

400Bad Request

codemissing_required_parameter

MeaningA required field was omitted

400Bad Request

codeinvalid_parameter_value

MeaningA field failed validation (bad enum, wrong type, etc.)

400Bad Request

codeparameter_too_long

MeaningA field exceeded its max length

400Bad Request

codeunsupported_parameter

MeaningAn update request included a field it doesn't accept

400Bad Request

codetoo_many_files

MeaningMore than one file uploaded to an instance create

400Bad Request

codeunsupported_file_type

MeaningFile extension not in the allowed list

400Bad Request

codefile_too_large

MeaningFile exceeds 100,000,000 bytes (100 MB)

400Bad Request

codeinvalid_id

MeaningThe dataset/instance id in the URL isn't a well-formed UUID

401Unauthorized

codeunauthorized

MeaningMissing, invalid, or expired bearer token

403Forbidden

codeinsufficient_permissions

MeaningYour account has no base access to this API

404Not Found

codedataset_not_found

MeaningDataset doesn't exist, or you lack access to it

404Not Found

codeinstance_not_found

MeaningInstance doesn't exist in that dataset, or you lack access

500Internal Server Error

codeinternal_error

MeaningUnexpected server error

503Service Unavailable

codeservice_unavailable

MeaningAuthorization backend temporarily unavailable — retry

Status	code	Meaning
400Bad Request	`missing_required_parameter`	A required field was omitted
400Bad Request	`invalid_parameter_value`	A field failed validation (bad enum, wrong type, etc.)
400Bad Request	`parameter_too_long`	A field exceeded its max length
400Bad Request	`unsupported_parameter`	An update request included a field it doesn't accept
400Bad Request	`too_many_files`	More than one file uploaded to an instance create
400Bad Request	`unsupported_file_type`	File extension not in the allowed list
400Bad Request	`file_too_large`	File exceeds 100,000,000 bytes (100 MB)
400Bad Request	`invalid_id`	The dataset/instance id in the URL isn't a well-formed UUID
401Unauthorized	`unauthorized`	Missing, invalid, or expired bearer token
403Forbidden	`insufficient_permissions`	Your account has no base access to this API
404Not Found	`dataset_not_found`	Dataset doesn't exist, or you lack access to it
404Not Found	`instance_not_found`	Instance doesn't exist in that dataset, or you lack access
500Internal Server Error	`internal_error`	Unexpected server error
503Service Unavailable	`service_unavailable`	Authorization 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:

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.

Knowledge Base API

Resources

Dataset object

Instance object

Datasets

Create a dataset

Create a Dataset

List datasets

List Datasets

Retrieve a dataset

Retrieve a Dataset

Update a dataset

Update a Dataset

Delete a dataset

Delete a Dataset

Get dataset stats

Get Dataset Stats

Instances

Create an instance (upload a document)

Create an Instance

List instances

List Instances

Retrieve an instance

Retrieve an Instance

Update an instance

Update an Instance

Delete an instance

Delete an Instance

Errors

Asynchronous processing

Using a dataset in Chat Completions

On this page

Knowledge Base API

ResourcesCopy Anchor Link

Dataset objectCopy Anchor Link

Instance objectCopy Anchor Link

DatasetsCopy Anchor Link

Create a datasetCopy Anchor Link

Create a Dataset

List datasetsCopy Anchor Link

List Datasets

Retrieve a datasetCopy Anchor Link

Retrieve a Dataset

Update a datasetCopy Anchor Link

Update a Dataset

Delete a datasetCopy Anchor Link

Delete a Dataset

Get dataset statsCopy Anchor Link

Get Dataset Stats

InstancesCopy Anchor Link

Create an instance (upload a document)Copy Anchor Link

Create an Instance

List instancesCopy Anchor Link

List Instances

Retrieve an instanceCopy Anchor Link

Retrieve an Instance

Update an instanceCopy Anchor Link

Update an Instance

Delete an instanceCopy Anchor Link

Delete an Instance

ErrorsCopy Anchor Link

Asynchronous processingCopy Anchor Link

Using a dataset in Chat CompletionsCopy Anchor Link

On this page

Resources

Dataset object

Instance object

Datasets

Create a dataset

List datasets

Retrieve a dataset

Update a dataset

Delete a dataset

Get dataset stats

Instances

Create an instance (upload a document)

List instances

Retrieve an instance

Update an instance

Delete an instance

Errors

Asynchronous processing

Using a dataset in Chat Completions