Collections API
Collection Management
The base URL for collection management is shared with Management API at https://management-api.x.ai/.
You have to authenticate using xAI Management API Key with the header Authorization: Bearer <your xAI Management API key>.
For more details on provisioning xAI Management API key and using Management API, you can visit
Create a collection
/v1/collections
Create a collection.
Request Body
collection_name
string
required
Name to use for the new collection.
Response Body
collection_id
string
UUIDv4 that represents an ID of the collection.
collection_name
string
Name of the collection.
created_at
string
The Unix timestamp for when the document was created.
index_configuration
object
chunk_configuration
object
documents_count
integer
How many files the collection contains.
field_definitions
array
Field definitions for documents in this collection. Defines what fields documents can have and their constraints.
collection_description
string
Optional description of the collection.
List all collections
/v1/collections
List all the collections a team has.
Query parameters
team_id
string
The ID of the team that owns the collections being listed. If not provided, the team ID will be derived from your request credentials.
limit
integer
A limit on the number of objects to be returned. Max 100 items per request. If not provided, set the default to 100 items.
order
string
The ordering to sort the returned collections. If not provided, the default order is Descending.
sort_by
string
The parameter that the collections will be sorted by. If not provided, the default is to sort by `collection_name`.
pagination_token
string
Optional token to retrieve the next page. Provided by `pagination_token` in a previous `ListCollectionsResponse`.
filter
string
Filter expression to narrow down results. Supports filtering on: collection_id, collection_name (partial string matching), created_at, documents_count Examples: - 'collection_id = "collection_123"' - 'collection_name:"SEC" AND documents_count:>10' - 'collection_name = "report"' (partial match) - 'created_at:>2025-01-01T00:00:00Z'
Response Body
collections
array
List of collections.
pagination_token
string
Token to be sent in the next ListCollectionsRequest's pagination_token for retrieving the next page.
Get metadata of a collection
/v1/collections/{collection_id}
Get a collection's metadata.
Path parameters
collection_id
string
required
The ID of the collection to request.
Query parameters
team_id
string
The ID of the team that owns the collection. If not provided, the team ID will be derived from your request credentials.
Response Body
collection_id
string
UUIDv4 that represents an ID of the collection.
collection_name
string
Name of the collection.
created_at
string
The Unix timestamp for when the document was created.
index_configuration
object
chunk_configuration
object
documents_count
integer
How many files the collection contains.
field_definitions
array
Field definitions for documents in this collection. Defines what fields documents can have and their constraints.
collection_description
string
Optional description of the collection.
Delete a collection
/v1/collections/{collection_id}
Delete a specific collection.
Path parameters
collection_id
string
required
The ID of the collection to delete.
Query parameters
team_id
string
The ID of the team that owns the collection. If not provided, the team ID will be derived from your request credentials.
Update a collection's configuration
/v1/collections/{collection_id}
Update collection's config.
Path parameters
collection_id
string
required
The ID of the collection to update.
Request Body
Response Body
collection_id
string
UUIDv4 that represents an ID of the collection.
collection_name
string
Name of the collection.
created_at
string
The Unix timestamp for when the document was created.
index_configuration
object
chunk_configuration
object
documents_count
integer
How many files the collection contains.
field_definitions
array
Field definitions for documents in this collection. Defines what fields documents can have and their constraints.
collection_description
string
Optional description of the collection.
Add existing document to a collection
/v1/collections/{collection_id}/documents/{file_id}
Add a document to collection.
Path parameters
collection_id
string
required
The id of the collection this document will be added to.
file_id
string
required
The ID of the document to use for this request.
Request Body
List documents in a collection
/v1/collections/{collection_id}/documents
List documents in a collection.
Path parameters
collection_id
string
required
The ID of the collection to list documents from.
Query parameters
team_id
string
The ID of the team owning the documents. If not provided, the team ID will be derived from your request credentials.
limit
integer
A limit on the number of objects to be returned. Max 100 items per request. If not provided, set the default to 100 items.
order
string
The ordering to sort the returned documents. If not provided, the default order is Descending.
sort_by
string
The parameter that the documents will be sorted by. If not provided, the default is to sort by `name`.
pagination_token
string
Optional token to retrieve the next page. Provided by `pagination_token` in a previous `ListDocumentsResponse`.
name
string
The name of the documents to get. DEPRECATED: Use filter field instead with "name:value"
filter
string
Filter expression to narrow down results. Supports filtering on file metadata (name, content_type, size_bytes, created_at) and document fields (status, fields.{key}) Examples: - 'status:DOCUMENT_STATUS_PROCESSED' - 'name:"quarterly" AND status:!DOCUMENT_STATUS_FAILED' - 'fields.isbn:"978-1-234567-89-0"' - 'size_bytes:>5000000 AND content_type:application/pdf'
Response Body
documents
array
List of documents.
pagination_token
string
Token to be sent in the next ListDocumentsRequest's pagination_token for retrieving the next page.
Retrieve document metadata
/v1/collections/{collection_id}/documents/{file_id}
Retrieve document metadata in a collection.
Path parameters
collection_id
string
required
The ID of the collection this document belongs to.
file_id
string
required
The ID of the document to use for this request.
Query parameters
team_id
string
The ID of the team the document belongs to. If not provided, the team ID will be derived from your request credentials.
Response Body
file_metadata
object
Metadata of an uploaded file.
Document-level fields as defined by the collection's field_definitions. These fields are validated against the collection's field definitions: - Required fields must be present - Unique fields must be unique within the collection - All fields are validated at upload/update time
object
Status of a document
"DOCUMENT_STATUS_UNKNOWN" | "DOCUMENT_STATUS_PROCESSING" | "DOCUMENT_STATUS_PROCESSED" | "DOCUMENT_STATUS_FAILED"
default: DOCUMENT_STATUS_UNKNOWN
error_message
string
Any error that occurred while processing.
last_indexed_at
string
Timestamp of when this document was last indexed. Empty if it hasn't been.
Regenerate indices for given document
/v1/collections/{collection_id}/documents/{file_id}
Regenerate indices for the given document.
Path parameters
collection_id
string
required
The ID of the collection that includes the document.
file_id
string
required
The ID of the file to update.
Query parameters
team_id
string
The ID of the team that owns the document. If not provided, the team ID will be derived from your request credentials.
Remove document from a collection
/v1/collections/{collection_id}/documents/{file_id}
Remove document from collection.
Path parameters
collection_id
string
required
The ID of the collection the document will be remove from.
file_id
string
required
The file ID of the document to use for this request.
Query parameters
team_id
string
The ID of the team that owns the collection. If not provided, the team ID will be derived from your request credentials.
Batch get document's metadata
/v1/collections/{collection_id}/documents:batchGet
Get documents metadata in a batch request.
Path parameters
collection_id
string
required
The ID of the collection that includes the documents.
Query parameters
team_id
string
The ID of the team that owns the document. If `None`, the team ID will be derived from your request credentials.
file_ids
array
required
The IDs of the files to retrieve the document metadata from.
Response Body
documents
array
Documents' metadata requested.
Did you find this page helpful?