# 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}},"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"]}}},"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"}}],"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}},"required":["file_name","external_id","original_file_name","original_file_path","original_author","extension","file_path","valid_from","valid_until","metadata","size_kb","storage"]},"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}},"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"]}}},"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}},"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"]}}},"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}},"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"]}}},"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"}}}}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://developers.whaly.io/api-reference/documents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.