> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/otari/for-integrators/api-reference/files.md).

# Files

## List Files

> List the authenticated user's uploaded files in the request's workspace.\
> \
> \`\`workspace\_id\`\` narrows a master-key listing to one workspace; a keyed\
> request is already confined to its key's own and cannot widen or move it.\
> \
> Each flavor pages with its own cursor.\
> OpenAI's \`\`after\`\` names the last file of the previous page, and \`\`has\_more\`\` says whether to ask again.\
> Anthropic's \`\`next\_page\`\` is passed back as \`\`page\`\`, and \`\`ids\[]\`\` reads up to 100 named files in one page.\
> A cursor whose file has since been deleted or has expired is still a position.\
> An \`\`after\`\` the caller never owned is a 404, and a \`\`page\`\` token this gateway did not issue is a 400.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OpenAIFileList":{"description":"A page of files in OpenAI's list shape, whose cursor is the last entry's ID.","properties":{"data":{"items":{"$ref":"#/components/schemas/OpenAIFileObject"},"title":"Data","type":"array"},"first_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Id"},"has_more":{"title":"Has More","type":"boolean"},"last_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Id"},"object":{"const":"list","default":"list","title":"Object","type":"string"}},"required":["data","has_more","first_id","last_id"],"title":"OpenAIFileList","type":"object"},"OpenAIFileObject":{"description":"One file in OpenAI's file object shape.","properties":{"bytes":{"title":"Bytes","type":"integer"},"created_at":{"title":"Created At","type":"integer"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"filename":{"title":"Filename","type":"string"},"id":{"title":"Id","type":"string"},"object":{"const":"file","default":"file","title":"Object","type":"string"},"purpose":{"title":"Purpose","type":"string"}},"required":["id","bytes","created_at","expires_at","filename","purpose"],"title":"OpenAIFileObject","type":"object"},"AnthropicFileList":{"description":"A page of files in Anthropic's list shape, whose cursor is an opaque token.","properties":{"data":{"items":{"$ref":"#/components/schemas/AnthropicFileMetadata"},"title":"Data","type":"array"},"next_page":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Page"}},"required":["data","next_page"],"title":"AnthropicFileList","type":"object"},"AnthropicFileMetadata":{"description":"One file in the ``FileMetadata`` shape of Anthropic's GA Files API.\n\n``expires_at`` is always present and ``None`` for a file kept indefinitely.\n``downloadable`` is always true, because the gateway serves every stored file's bytes back.","properties":{"created_at":{"title":"Created At","type":"string"},"downloadable":{"const":true,"default":true,"title":"Downloadable","type":"boolean"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"filename":{"title":"Filename","type":"string"},"id":{"title":"Id","type":"string"},"mime_type":{"title":"Mime Type","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"type":{"const":"file","default":"file","title":"Type","type":"string"}},"required":["id","filename","mime_type","size_bytes","created_at","expires_at"],"title":"AnthropicFileMetadata","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/files":{"get":{"description":"List the authenticated user's uploaded files in the request's workspace.\n\n``workspace_id`` narrows a master-key listing to one workspace; a keyed\nrequest is already confined to its key's own and cannot widen or move it.\n\nEach flavor pages with its own cursor.\nOpenAI's ``after`` names the last file of the previous page, and ``has_more`` says whether to ask again.\nAnthropic's ``next_page`` is passed back as ``page``, and ``ids[]`` reads up to 100 named files in one page.\nA cursor whose file has since been deleted or has expired is still a position.\nAn ``after`` the caller never owned is a 404, and a ``page`` token this gateway did not issue is a 400.","operationId":"files-list_files","parameters":[{"in":"query","name":"user","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User"}},{"in":"query","name":"purpose","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose"}},{"in":"query","name":"workspace_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"title":"Workspace Id"}},{"in":"query","name":"limit","required":false,"schema":{"default":100,"maximum":1000,"minimum":1,"title":"Limit","type":"integer"}},{"in":"query","name":"after","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"After"}},{"in":"query","name":"order","required":false,"schema":{"default":"desc","enum":["asc","desc"],"title":"Order","type":"string"}},{"in":"query","name":"page","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Page"}},{"in":"query","name":"ids[]","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ids[]"}}],"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OpenAIFileList"},{"$ref":"#/components/schemas/AnthropicFileList"}],"title":"Response Files-List Files"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List Files","tags":["files"]}}}}
```

## Create File

> Upload a file. Answers in the OpenAI or Anthropic file shape, following the caller's headers.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"Body_files-create_file":{"properties":{"file":{"contentMediaType":"application/octet-stream","title":"File","type":"string"},"purpose":{"default":"user_data","title":"Purpose","type":"string"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User"}},"required":["file"],"title":"Body_files-create_file","type":"object"},"OpenAIFileObject":{"description":"One file in OpenAI's file object shape.","properties":{"bytes":{"title":"Bytes","type":"integer"},"created_at":{"title":"Created At","type":"integer"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"filename":{"title":"Filename","type":"string"},"id":{"title":"Id","type":"string"},"object":{"const":"file","default":"file","title":"Object","type":"string"},"purpose":{"title":"Purpose","type":"string"}},"required":["id","bytes","created_at","expires_at","filename","purpose"],"title":"OpenAIFileObject","type":"object"},"AnthropicFileMetadata":{"description":"One file in the ``FileMetadata`` shape of Anthropic's GA Files API.\n\n``expires_at`` is always present and ``None`` for a file kept indefinitely.\n``downloadable`` is always true, because the gateway serves every stored file's bytes back.","properties":{"created_at":{"title":"Created At","type":"string"},"downloadable":{"const":true,"default":true,"title":"Downloadable","type":"boolean"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"filename":{"title":"Filename","type":"string"},"id":{"title":"Id","type":"string"},"mime_type":{"title":"Mime Type","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"type":{"const":"file","default":"file","title":"Type","type":"string"}},"required":["id","filename","mime_type","size_bytes","created_at","expires_at"],"title":"AnthropicFileMetadata","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/files":{"post":{"description":"Upload a file. Answers in the OpenAI or Anthropic file shape, following the caller's headers.","operationId":"files-create_file","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_files-create_file"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OpenAIFileObject"},{"$ref":"#/components/schemas/AnthropicFileMetadata"}],"title":"Response Files-Create File"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Create File","tags":["files"]}}}}
```

## Get File

> Retrieve metadata for a single file.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OpenAIFileObject":{"description":"One file in OpenAI's file object shape.","properties":{"bytes":{"title":"Bytes","type":"integer"},"created_at":{"title":"Created At","type":"integer"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"filename":{"title":"Filename","type":"string"},"id":{"title":"Id","type":"string"},"object":{"const":"file","default":"file","title":"Object","type":"string"},"purpose":{"title":"Purpose","type":"string"}},"required":["id","bytes","created_at","expires_at","filename","purpose"],"title":"OpenAIFileObject","type":"object"},"AnthropicFileMetadata":{"description":"One file in the ``FileMetadata`` shape of Anthropic's GA Files API.\n\n``expires_at`` is always present and ``None`` for a file kept indefinitely.\n``downloadable`` is always true, because the gateway serves every stored file's bytes back.","properties":{"created_at":{"title":"Created At","type":"string"},"downloadable":{"const":true,"default":true,"title":"Downloadable","type":"boolean"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"filename":{"title":"Filename","type":"string"},"id":{"title":"Id","type":"string"},"mime_type":{"title":"Mime Type","type":"string"},"size_bytes":{"title":"Size Bytes","type":"integer"},"type":{"const":"file","default":"file","title":"Type","type":"string"}},"required":["id","filename","mime_type","size_bytes","created_at","expires_at"],"title":"AnthropicFileMetadata","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/files/{file_id}":{"get":{"description":"Retrieve metadata for a single file.","operationId":"files-get_file","parameters":[{"in":"path","name":"file_id","required":true,"schema":{"title":"File Id","type":"string"}},{"in":"query","name":"user","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User"}}],"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OpenAIFileObject"},{"$ref":"#/components/schemas/AnthropicFileMetadata"}],"title":"Response Files-Get File"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get File","tags":["files"]}}}}
```

## Delete File

> Soft-delete a file's metadata and remove its bytes from the backend.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"OpenAIFileDeleted":{"description":"OpenAI's answer to a delete.","properties":{"deleted":{"const":true,"default":true,"title":"Deleted","type":"boolean"},"id":{"title":"Id","type":"string"},"object":{"const":"file","default":"file","title":"Object","type":"string"}},"required":["id"],"title":"OpenAIFileDeleted","type":"object"},"AnthropicFileDeleted":{"description":"Anthropic's answer to a delete.","properties":{"id":{"title":"Id","type":"string"},"type":{"const":"file_deleted","default":"file_deleted","title":"Type","type":"string"}},"required":["id"],"title":"AnthropicFileDeleted","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/files/{file_id}":{"delete":{"description":"Soft-delete a file's metadata and remove its bytes from the backend.","operationId":"files-delete_file","parameters":[{"in":"path","name":"file_id","required":true,"schema":{"title":"File Id","type":"string"}},{"in":"query","name":"user","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User"}}],"responses":{"200":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OpenAIFileDeleted"},{"$ref":"#/components/schemas/AnthropicFileDeleted"}],"title":"Response Files-Delete File"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Delete File","tags":["files"]}}}}
```

## Get File Content

> Download the raw bytes of a file, streamed rather than buffered whole.

```json
{"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/files/{file_id}/content":{"get":{"description":"Download the raw bytes of a file, streamed rather than buffered whole.","operationId":"files-get_file_content","parameters":[{"in":"path","name":"file_id","required":true,"schema":{"title":"File Id","type":"string"}},{"in":"query","name":"user","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User"}}],"responses":{"200":{"content":{"*/*":{"schema":{"format":"binary","type":"string"}},"application/octet-stream":{"schema":{"format":"binary","type":"string"}}},"description":"File content. Content-Type reflects the stored media type; application/octet-stream is the fallback.","headers":{"Content-Disposition":{"description":"Attachment filename, with a UTF-8 filename* parameter for non-ASCII names.","schema":{"type":"string"}}}},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get File Content","tags":["files"]}}}}
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.otari.ai/otari/for-integrators/api-reference/files.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.