English Docs
API Console

Collections API

Collection Management

View as Markdown
Create API key Learn Grok 4.7

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>.

Create a collection

/v1/collections

Create a collection.

Request Body

collection_namestring

Name to use for the new collection.

Response Body

collection_idstring

UUIDv4 that represents an ID of the collection.

collection_namestring

Name of the collection.

created_atstring

The Unix timestamp for when the document was created.

index_configurationobject

chunk_configurationobject

documents_countinteger

How many files the collection contains.

field_definitionsarray<object>

Field definitions for documents in this collection. Defines what fields documents can have and their constraints.

collection_descriptionstring

Optional description of the collection.

Exampletext

text

{
  "collection_name": "SEC Filings",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true
  },
  "collection_description": "Filings from the SEC for financial analysis"
}
Exampletext

text

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

List all collections

/v1/collections

List all the collections a team has.

Query Parameters

team_idstring

The ID of the team that owns the collections being listed. If not provided, the team ID will be derived from your request credentials.

limitinteger

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"ORDERING_UNKNOWN" | "ORDERING_ASCENDING" | "ORDERING_DESCENDING"

The ordering to sort the returned collections. If not provided, the default order is Descending.

sort_by"COLLECTIONS_SORT_BY_NAME" | "COLLECTIONS_SORT_BY_AGE"

The parameter that the collections will be sorted by. If not provided, the default is to sort by `collection_name`.

pagination_tokenstring

Optional token to retrieve the next page. Provided by `pagination_token` in a previous `ListCollectionsResponse`.

filterstring

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

collectionsarray<object>

List of collections.

pagination_tokenstring

Token to be sent in the next `ListCollectionsRequest`'s `pagination_token` for retrieving the next page.

Exampletext

text

No parameters.
Exampletext

text

{
  "collections": [
    {
      "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
      "collection_name": "SEC Filings",
      "created_at": "2025-09-16T18:36:09.790629Z",
      "index_configuration": {
        "model_name": "grok-embedding-small"
      },
      "chunk_configuration": {
        "tokens_configuration": {
          "max_chunk_size_tokens": 1024,
          "chunk_overlap_tokens": 200,
          "encoding_name": "o200k_base"
        },
        "strip_whitespace": true,
        "inject_name_into_chunks": false
      },
      "documents_count": 0,
      "collection_type": "text",
      "collection_description": "Filings from the SEC for financial analysis"
    }
  ]
}

Get metadata of a collection

/v1/collections/{collection_id}

Get a collection's metadata.

Path Parameters

collection_idstring

The ID of the collection to request.

Query Parameters

team_idstring

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_idstring

UUIDv4 that represents an ID of the collection.

collection_namestring

Name of the collection.

created_atstring

The Unix timestamp for when the document was created.

index_configurationobject

chunk_configurationobject

documents_countinteger

How many files the collection contains.

field_definitionsarray<object>

Field definitions for documents in this collection. Defines what fields documents can have and their constraints.

collection_descriptionstring

Optional description of the collection.

Exampletext

text

No parameters.
Exampletext

text

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

Delete a collection

/v1/collections/{collection_id}

Delete a specific collection.

Path Parameters

collection_idstring

The ID of the collection to delete.

Query Parameters

team_idstring

The ID of the team that owns the collection. If not provided, the team ID will be derived from your request credentials.

Exampletext

text

No parameters.
Exampletext

text

{}

Update a collection's configuration

/v1/collections/{collection_id}

Update collection's config.

Path Parameters

collection_idstring

The ID of the collection to update.

Request Body

Response Body

collection_idstring

UUIDv4 that represents an ID of the collection.

collection_namestring

Name of the collection.

created_atstring

The Unix timestamp for when the document was created.

index_configurationobject

chunk_configurationobject

documents_countinteger

How many files the collection contains.

field_definitionsarray<object>

Field definitions for documents in this collection. Defines what fields documents can have and their constraints.

collection_descriptionstring

Optional description of the collection.

Exampletext

text

{
  "collectionName": "SEC Filings (New)",
  "chunkConfiguration": {
    "tokensConfiguration": {
      "maxChunkSizeTokens": 1024,
      "chunkOverlapTokens": 200,
      "encodingName": "o200k_base"
    },
    "stripWhitespace": true,
    "injectNameIntoChunks": false
  },
  "collectionDescription": "Updated description of the collection"
}
Exampletext

text

{
  "collection_id": "collection_80100614-300c-4609-959b-a138fa90f542",
  "collection_name": "SEC Filings",
  "created_at": "2025-09-16T18:36:09.790629Z",
  "index_configuration": {
    "model_name": "grok-embedding-small"
  },
  "chunk_configuration": {
    "tokens_configuration": {
      "max_chunk_size_tokens": 1024,
      "chunk_overlap_tokens": 200,
      "encoding_name": "o200k_base"
    },
    "strip_whitespace": true,
    "inject_name_into_chunks": false
  },
  "documents_count": 0,
  "collection_description": "Filings from the SEC for financial analysis"
}

Add existing document to a collection

/v1/collections/{collection_id}/documents/{file_id}

Add a document to collection.

Path Parameters

collection_idstring

The id of the collection this document will be added to.

file_idstring

The ID of the document to use for this request.

Request Body

Exampletext

text

{
  "fields": {
    "type": "10-Q"
  }
}
Exampletext

text

{}

List documents in a collection

/v1/collections/{collection_id}/documents

List documents in a collection.

Path Parameters

collection_idstring

The ID of the collection to list documents from.

Query Parameters

team_idstring

The ID of the team owning the documents. If not provided, the team ID will be derived from your request credentials.

limitinteger

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"ORDERING_UNKNOWN" | "ORDERING_ASCENDING" | "ORDERING_DESCENDING"

The ordering to sort the returned documents. If not provided, the default order is Descending.

sort_by"DOCUMENTS_SORT_BY_NAME" | "DOCUMENTS_SORT_BY_SIZE" | "DOCUMENTS_SORT_BY_AGE"

The parameter that the documents will be sorted by. If not provided, the default is to sort by `name`.

pagination_tokenstring

Optional token to retrieve the next page. Provided by `pagination_token` in a previous `ListDocumentsResponse`.

namestring

The name of the documents to get. DEPRECATED: Use filter field instead with "name:value"

filterstring

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

documentsarray<object>

List of documents.

pagination_tokenstring

Token to be sent in the next `ListDocumentsRequest`'s `pagination_token` for retrieving the next page.

Exampletext

text

No parameters.
Exampletext

text

{
  "documents": [
    {
      "file_metadata": {
        "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
        "name": "tsla-20250630.txt",
        "size_bytes": "119237",
        "content_type": "text/plain",
        "created_at": "2025-09-16T19:06:53.472088Z",
        "expires_at": null,
        "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
      },
      "fields": {
        "type": "10-Q"
      },
      "status": "DOCUMENT_STATUS_PROCESSED",
      "error_message": ""
    }
  ]
}

Retrieve document metadata

/v1/collections/{collection_id}/documents/{file_id}

Retrieve document metadata in a collection.

Path Parameters

collection_idstring

The ID of the collection this document belongs to.

file_idstring

The ID of the document to use for this request.

Query Parameters

team_idstring

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_metadataobject

Metadata of an uploaded file.

fieldsobject

status"DOCUMENT_STATUS_UNKNOWN" | "DOCUMENT_STATUS_PROCESSING" | "DOCUMENT_STATUS_PROCESSED" | "DOCUMENT_STATUS_FAILED"

error_messagestring

Any error that occurred while processing.

last_indexed_atstring

Timestamp of when this document was last indexed. Empty if it hasn't been.

Exampletext

text

No parameters.
Exampletext

text

{
  "file_metadata": {
    "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
    "name": "tsla-20250630.txt",
    "size_bytes": "119237",
    "content_type": "text/plain",
    "created_at": "2025-09-16T19:06:53.472088Z",
    "expires_at": null,
    "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
  },
  "fields": {
    "type": "10-Q"
  },
  "status": "DOCUMENT_STATUS_PROCESSED",
  "error_message": ""
}

Regenerate indices for given document

/v1/collections/{collection_id}/documents/{file_id}

Regenerate indices for the given document.

Path Parameters

collection_idstring

The ID of the collection that includes the document.

file_idstring

The ID of the file to update.

Query Parameters

team_idstring

The ID of the team that owns the document. If not provided, the team ID will be derived from your request credentials.

Exampletext

text

No parameters.
Exampletext

text

{}

Remove document from a collection

/v1/collections/{collection_id}/documents/{file_id}

Remove document from collection.

Path Parameters

collection_idstring

The ID of the collection the document will be remove from.

file_idstring

The file ID of the document to use for this request.

Query Parameters

team_idstring

The ID of the team that owns the collection. If not provided, the team ID will be derived from your request credentials.

Exampletext

text

No parameters.
Exampletext

text

{}

Batch get document's metadata

/v1/collections/{collection_id}/documents:batchGet

Get documents metadata in a batch request.

Path Parameters

collection_idstring

The ID of the collection that includes the documents.

Query Parameters

team_idstring

The ID of the team that owns the document. If `None`, the team ID will be derived from your request credentials.

file_idsarray<string>

The IDs of the files to retrieve the document metadata from.

Response Body

documentsarray<object>

Documents' metadata requested.

Exampletext

text

No parameters.
Exampletext

text

{
  "documents": [
    {
      "file_metadata": {
        "file_id": "file_94847856-a56f-4b1e-82dd-7fe0b3af43d9",
        "name": "tsla-20250630.txt",
        "size_bytes": "119237",
        "content_type": "text/plain",
        "created_at": "2025-09-16T19:06:53.472088Z",
        "expires_at": null,
        "hash": "a15b2225695f242af60e5d99a7455b0a2e371dac88283401ebc013dba1dfbc84"
      },
      "fields": {},
      "status": "DOCUMENT_STATUS_PROCESSED",
      "error_message": ""
    }
  ]
}

Last updated:June 11, 2026