> For the complete documentation index, see [llms.txt](https://developers.whaly.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.whaly.io/api-reference/documents.md).

# Documents

## GET /v1/documents

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"PaginatedListWrapper":{"type":"object","properties":{"paging":{"$ref":"#/components/schemas/PagingInfo"}},"required":["paging"]},"PagingInfo":{"type":"object","properties":{"next":{"$ref":"#/components/schemas/PagingNext"}},"required":["next"]},"PagingNext":{"type":"object","properties":{"after":{"type":"string"}},"required":["after"]},"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents":{"get":{"operationId":"DocumentsController_listAll","parameters":[{"name":"after","required":false,"in":"query","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"number"}},{"name":"externalId","required":false,"in":"query","schema":{"type":"string"}},{"name":"document_source_id","required":false,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedListWrapper"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentDto"}}}}]}}}}}}}}}
```

## POST /v1/documents

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"CreateDocumentDto":{"type":"object","properties":{"file_name":{"type":"string","description":"A user friendly name for the document","nullable":false},"external_id":{"type":"string","description":"The id generated by the system from which the document was extracted"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to. Optional — when omitted, the document is attached to the org's default source.","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI). Defaults to false.","nullable":true}},"required":["file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]},"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents":{"post":{"operationId":"DocumentsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDocumentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}}}}}}}
```

## GET /v1/documents/{documentId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents/{documentId}":{"get":{"operationId":"DocumentsController_findOne","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}}}}}}}
```

## PUT /v1/documents/{documentId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"DocumentDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique ID"},"file_name":{"type":"string","description":"A user friendly name for the document"},"external_id":{"type":"string","description":"The id generated by the system of referenced"},"original_file_name":{"type":"string","description":"The file name as of the extracted file.","nullable":true},"original_file_path":{"type":"string","description":"The file path of the extracted file.","nullable":true},"original_author":{"type":"string","description":"The author of the document.","nullable":true},"extension":{"type":"string","description":"The file extension."},"file_path":{"type":"string","description":"The file path as stored in the object storage."},"valid_from":{"type":"string","description":"The date at which the document has been made available.","nullable":true},"valid_until":{"type":"string","description":"The date at which the document will be made unavailable.","nullable":true},"metadata":{"type":"object","description":"The metadata of the document. You can add 20 total key-value pairs within these data limits:\n- key: 40 character limit. Square brackets ([ ]) can't be included in keys.\n- value: 300 character limit.","nullable":true,"additionalProperties":{"type":"string"}},"size_kb":{"type":"number","description":"The file size in kb.","nullable":true},"storage":{"type":"string","description":"The object storage ID to which the document is associated","nullable":false},"document_source_id":{"type":"string","description":"The document source ID this document belongs to","nullable":true},"is_externally_managed":{"type":"boolean","description":"Whether the document is externally managed (read-only in the UI)"}},"required":["id","file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage","document_source_id","is_externally_managed"]}}},"paths":{"/v1/documents/{documentId}":{"put":{"operationId":"DocumentsController_update","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDto"}}}}}}}}}
```

## DELETE /v1/documents/{documentId}

>

```json
{"openapi":"3.0.0","info":{"title":"Whaly API","version":"1.0"},"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"Pass a Service Account Key as the Bearer token to authenticate. e.g. 'sk:xxxxxxx'"}},"schemas":{"DocumentDeleteResultDto":{"type":"object","properties":{"id":{"type":"string"},"isDeleted":{"type":"boolean"}},"required":["id","isDeleted"]}}},"paths":{"/v1/documents/{documentId}":{"delete":{"operationId":"DocumentsController_delete","parameters":[{"name":"documentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDeleteResultDto"}}}}}}}}}
```