> For the complete documentation index, see [llms.txt](https://guides.ia.numerique.gouv.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/documents.md).

# Documents

## Get Documents

> Get all documents ID from a collection.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents":{"get":{"tags":["Documents"],"summary":"Get Documents","description":"Get all documents ID from a collection.","operationId":"get_documents_v1_documents_get","parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter documents by name","title":"Name"},"description":"Filter documents by name"},{"name":"collection_id","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"description":"Filter documents by collection ID","title":"Collection Id"},"description":"Filter documents by collection ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The number of documents to return","default":10,"title":"Limit"},"description":"The number of documents to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","description":"The offset of the first document to return","default":0,"title":"Offset"},"description":"The offset of the first document to return"},{"name":"order_by","in":"query","required":false,"schema":{"enum":["id","name","created"],"type":"string","description":"The order by field to sort the documents by.","default":"id","title":"Order By"},"description":"The order by field to sort the documents by."},{"name":"order_direction","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","description":"The direction to order the documents by.","default":"asc","title":"Order Direction"},"description":"The direction to order the documents by."},{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Document

> Upload a file, parse and split it into chunks, then create a document. If no file is provided, the document will be created without content, use POST \`/v1/documents/{document\_id}/chunks\` to fill it.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"Body_create_document_v1_documents_post":{"properties":{"file":{"anyOf":[{"type":"string","contentMediaType":"application/octet-stream"},{"type":"null"}],"title":"File","description":"The file to create a document from. If not provided, the document will be created without content, use POST `/v1/documents/{document_id}/chunks` to fill it."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Name of document if no file is provided or to override file name."},"collection_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Collection Id","description":"The collection ID to use for the file upload. The file will be vectorized with model defined by the collection."},"collection":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Collection","deprecated":true},"disable_chunking":{"type":"boolean","title":"Disable Chunking","description":"Whether to disable `RecursiveCharacterTextSplitter` chunking for the upload file.","default":false},"chunk_size":{"type":"integer","minimum":0,"title":"Chunk Size","description":"The size in characters of the chunks to use for the upload file. If not provided, the document will not be split into chunks.","default":2048},"chunk_min_size":{"type":"integer","minimum":0,"title":"Chunk Min Size","description":"The minimum size in characters of the chunks to use for the upload file.","default":0},"chunk_overlap":{"type":"integer","minimum":0,"title":"Chunk Overlap","description":"The overlap in characters of the chunks to use for the upload file.","default":0},"is_separator_regex":{"type":"boolean","title":"Is Separator Regex","description":"Whether the separator is a regex to use for the upload file.","default":false},"separators":{"items":{"type":"string"},"type":"array","minItems":0,"title":"Separators","description":"Delimiters used by RecursiveCharacterTextSplitter for further splitting. If provided, `preset_separators` is ignored.","default":[]},"preset_separators":{"$ref":"#/components/schemas/PresetSeparators","description":"Preset separators used by RecursiveCharacterTextSplitter for further splitting. See [implemented details](https://github.com/langchain-ai/langchain/blob/eb122945832eae9b9df7c70ccd8d51fcd7a1899b/libs/text-splitters/langchain_text_splitters/character.py#L164).","default":"markdown"},"metadata":{"type":"string","title":"Metadata","description":"Optional additional metadata to add to each chunk if a file is provided. Provide a stringified JSON object matching the Metadata schema.","default":""}},"type":"object","title":"Body_create_document_v1_documents_post"},"PresetSeparators":{"type":"string","enum":["cpp","go","java","kotlin","js","ts","php","proto","python","r","rst","ruby","rust","scala","swift","markdown","latex","html","sol","csharp","cobol","c","lua","perl","haskell","elixir","powershell","visualbasic6"],"title":"PresetSeparators"},"DocumentResponse":{"properties":{"id":{"type":"integer","minimum":0,"title":"Id","description":"The ID of the document created."}},"additionalProperties":true,"type":"object","required":["id"],"title":"DocumentResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents":{"post":{"tags":["Documents"],"summary":"Create Document","description":"Upload a file, parse and split it into chunks, then create a document. If no file is provided, the document will be created without content, use POST `/v1/documents/{document_id}/chunks` to fill it.","operationId":"create_document_v1_documents_post","parameters":[{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_create_document_v1_documents_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Document

> Get a document by ID.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"Document":{"properties":{"object":{"type":"string","const":"document","title":"Object","description":"The type of the object.","default":"document"},"id":{"type":"integer","exclusiveMinimum":0,"title":"Id","description":"The ID of the document."},"name":{"type":"string","minLength":1,"title":"Name","description":"The name of the document."},"collection_id":{"type":"integer","exclusiveMinimum":0,"title":"Collection Id","description":"The ID of the collection the document belongs to."},"created":{"type":"integer","title":"Created","description":"The date of the document creation."},"chunks":{"type":"integer","minimum":0,"title":"Chunks","description":"The number of chunks the document has.","default":0},"size":{"type":"integer","minimum":0,"title":"Size","description":"The size of the document in tokens.","default":0}},"additionalProperties":true,"type":"object","required":["id","name","collection_id","created"],"title":"Document"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document","description":"Get a document by ID.","operationId":"get_document_v1_documents__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","minimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete Document

> Delete a document.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}":{"delete":{"tags":["Documents"],"summary":"Delete Document","description":"Delete a document.","operationId":"delete_document_v1_documents__document_id__delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Document Chunks

> Get chunks of a document.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks":{"get":{"tags":["Documents"],"summary":"Get Document Chunks","description":"Get chunks of a document.","operationId":"get_document_chunks_v1_documents__document_id__chunks_get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"The number of chunks to return","default":10,"title":"Limit"},"description":"The number of chunks to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","description":"The offset of the first chunk to return","default":0,"title":"Offset"},"description":"The offset of the first chunk to return"},{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Document Chunks

> Fill document with chunks.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CreateChunks":{"properties":{"chunks":{"items":{"$ref":"#/components/schemas/InputChunk"},"type":"array","maxItems":64,"minItems":1,"title":"Chunks","description":"The list of chunks to create."}},"additionalProperties":true,"type":"object","required":["chunks"],"title":"CreateChunks"},"InputChunk":{"properties":{"content":{"type":"string","title":"Content","description":"The content of the chunk."},"metadata":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"integer","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"number","maximum":10000000000000000,"minimum":-10000000000000000},{"type":"boolean"}]},"propertyNames":{"maxLength":255,"minLength":1},"type":"object","maxProperties":10,"minProperties":1,"description":"Extra metadata for the source"},{"type":"null"}],"title":"Metadata","description":"Metadata of the chunk"}},"additionalProperties":true,"type":"object","required":["content"],"title":"InputChunk"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks":{"post":{"tags":["Documents"],"summary":"Create Document Chunks","description":"Fill document with chunks.","operationId":"create_document_chunks_v1_documents__document_id__chunks_post","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChunks"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Document Chunk

> Get a chunk of a document.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks/{chunk_id}":{"get":{"tags":["Documents"],"summary":"Get Document Chunk","description":"Get a chunk of a document.","operationId":"get_document_chunk_v1_documents__document_id__chunks__chunk_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"chunk_id","in":"path","required":true,"schema":{"type":"integer","minimum":0,"description":"The chunk ID","title":"Chunk Id"},"description":"The chunk ID"},{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete Document Chunk

> Delete a chunk of a document.

```json
{"openapi":"3.1.0","info":{"title":"Albert API","version":"0.4.9"},"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/documents/{document_id}/chunks/{chunk_id}":{"delete":{"tags":["Documents"],"summary":"Delete Document Chunk","description":"Delete a chunk of a document.","operationId":"delete_document_chunk_v1_documents__document_id__chunks__chunk_id__delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"description":"The document ID","title":"Document Id"},"description":"The document ID"},{"name":"chunk_id","in":"path","required":true,"schema":{"type":"integer","minimum":0,"description":"The chunk ID","title":"Chunk Id"},"description":"The chunk ID"},{"name":"required","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Required"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guides.ia.numerique.gouv.fr/albert-api/api-reference/liste-des-endpoint/documents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.