List Documents

List Documents

curl --request GET \
  --url https://api.contextual.ai/v1/datastores/{datastore_id}/documents \
  --header 'Authorization: Bearer <token>'

{
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "pending",
      "created_at": "<string>",
      "custom_metadata": {},
      "custom_metadata_config": {},
      "updated_at": "<string>",
      "ingestion_config": {},
      "has_access": true
    }
  ],
  "total_count": 123,
  "next_cursor": "<string>"
}

GET

datastores

{datastore_id}

documents

List Documents

curl --request GET \
  --url https://api.contextual.ai/v1/datastores/{datastore_id}/documents \
  --header 'Authorization: Bearer <token>'

{
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "status": "pending",
      "created_at": "<string>",
      "custom_metadata": {},
      "custom_metadata_config": {},
      "updated_at": "<string>",
      "ingestion_config": {},
      "has_access": true
    }
  ],
  "total_count": 123,
  "next_cursor": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

datastore_id

string<uuid>

required

Datastore ID of the datastore to retrieve documents for

Query Parameters

limit

integer

default:1000

Maximum number of documents to return

Required range: 1 <= x <= 1000

cursor

string

Cursor from the previous call to list documents, used to retrieve the next set of results

ingestion_job_status

enum<string>[]

Filters documents whose ingestion job status matches (one of) the provided status(es).

Available options:

pending,

processing,

retrying,

completed,

failed,

cancelled

uploaded_after

string<date-time>

Filters documents uploaded at or after specified timestamp.

uploaded_before

string<date-time>

Filters documents uploaded at or before specified timestamp.

document_name_prefix

string

Filters documents with the given prefix.

document_name_search

string

Filters documents whose name contains the search term (case-insensitive substring match).

Response

Successful Response

Response body from GET /data/documents

documents

DocumentDescription · object[]

required

List of documents retrieved based on the user's GET request

Show child attributes

documents.id

string<uuid>

required

ID of the document that was ingested

documents.name

string

required

User specified name of the document

documents.status

enum<string>

required

Status of this document's ingestion job

Available options:

pending,

processing,

retrying,

completed,

failed,

cancelled

documents.created_at

string

required

Timestamp of when the document was created in ISO format.

documents.custom_metadata

Custom Metadata · object

Custom metadata for the document, provided by the user at ingestion time.Must be a JSON-serializable dictionary with string keys and simple primitive values (str, int, float, bool). The total size must not exceed 2 KB.The strings with date format must stay in date format or be avodied if not in date format.The 'custom_metadata.url' field is automatically included in returned attributions during query time, if provided.The default maximum metadata fields that can be used is 15, contact support if more is needed.

Show child attributes

documents.custom_metadata.{key}

documents.custom_metadata_config

Custom Metadata Config · object

A dictionary mapping metadata field names to the configuration to use for each field. If a metadata field is not present in the dictionary, the default configuration will be used. If the dictionary is not provided, metadata will be added in context for rerank and generation but will not be returned back to the user in retrievals in query API. Limits:

Maximum characters per metadata field (for prompt or rerank): 400
Maximum number of metadata fields (for prompt or retrieval): 10 Contact [email protected] to request quota increases.

Show child attributes

documents.custom_metadata_config.{key}

MetadataFieldConfig · object

Show child attributes

documents.custom_metadata_config.{key}.in_chunks

boolean

default:true

Whether to add in chunks. Defaults to True. The maximum amount of characters per metadata field that can be added to the prompt or rerank is 400. The maximum amount of metadata fields that can be added for prompt or retrieval is 10. Contact [email protected] to request quota increases.

documents.custom_metadata_config.{key}.returned_in_response

boolean

default:false

Whether to add in response. Defaults to False

documents.custom_metadata_config.{key}.filterable

boolean

default:true

Whether to use in filtering. Defaults to True

documents.updated_at

string

Timestamp of when the document was modified in ISO format.

documents.ingestion_config

Ingestion Config · object

Ingestion configuration for the document when the document was ingested. It may be different from the current datastore configuration.

documents.has_access

boolean

default:true

Whether the user has access to this document.

total_count

integer

Total number of available documents which would be returned by the request if no limit were specified. Ommitted if job_id was set in the request.

next_cursor

string

Next cursor to continue pagination. Ommitted if there are no more documents after these ones, or if job_id was set in the request.

Get Datastore Metadata

Ingest Document

⌘I

/datastores

/datastores/{id}/documents

/agents

/contents

/agents/{id}/query

/lmunit

/users

/generate

/rerank

/parse

/workspaces

/billing

Authorizations

Path Parameters

Query Parameters

Response