# Files

## Upload File

> Upload a file with optional metadata.

```json
{"openapi":"3.1.0","info":{"title":"Activeloop Deep Research API","version":"1.0.0"},"servers":[{"url":"https://api.activeloop.ai","description":"Production server"},{"url":"https://api-beta.activeloop.dev","description":"Beta server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your bearer token in the format 'your-token' (without quotes or 'Bearer' prefix)"}},"schemas":{"Body_upload_file_files_post":{"properties":{"file":{"items":{"type":"string","format":"binary"},"type":"array","title":"File"},"purpose":{"$ref":"#/components/schemas/FilePurpose","default":"user_data"},"metadata":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metadata","description":"JSON string with file metadata"},"instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instructions","description":"Instructions used to process the file"},"workspace":{"type":"string","title":"Workspace","default":"default"}},"type":"object","title":"Body_upload_file_files_post"},"FilePurpose":{"type":"string","enum":["batch","batch_output","vision","user_data","evals"],"title":"FilePurpose"},"FileObject":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","title":"Object","default":"file"},"bytes":{"type":"integer","title":"Bytes"},"created_at":{"type":"integer","title":"Created At"},"filename":{"type":"string","title":"Filename"},"purpose":{"anyOf":[{"$ref":"#/components/schemas/FilePurpose"},{"type":"null"}],"default":"user_data"},"status":{"$ref":"#/components/schemas/FileStatus","default":"uploaded"},"status_details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Details"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"},"workspace_id":{"type":"string","title":"Workspace Id","default":"default"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["id","bytes","created_at","filename"],"title":"FileObject"},"FileStatus":{"type":"string","enum":["uploaded","parsed","indexed","upload_failed","parse_failed","index_failed","parsing","indexing"],"title":"FileStatus"},"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files":{"post":{"summary":"Upload File","description":"Upload a file with optional metadata.","operationId":"upload_file_files_post","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_file_files_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/FileObject"}},{"$ref":"#/components/schemas/FileObject"}],"title":"Response Upload File Files Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List Files

> Returns a list of files, filtered by the organization.

```json
{"openapi":"3.1.0","info":{"title":"Activeloop Deep Research API","version":"1.0.0"},"servers":[{"url":"https://api.activeloop.ai","description":"Production server"},{"url":"https://api-beta.activeloop.dev","description":"Beta server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your bearer token in the format 'your-token' (without quotes or 'Bearer' prefix)"}},"schemas":{"FilePurpose":{"type":"string","enum":["batch","batch_output","vision","user_data","evals"],"title":"FilePurpose"},"FileList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FileObject"},"type":"array","title":"Data"},"object":{"type":"string","title":"Object","default":"list"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["data","total"],"title":"FileList"},"FileObject":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","title":"Object","default":"file"},"bytes":{"type":"integer","title":"Bytes"},"created_at":{"type":"integer","title":"Created At"},"filename":{"type":"string","title":"Filename"},"purpose":{"anyOf":[{"$ref":"#/components/schemas/FilePurpose"},{"type":"null"}],"default":"user_data"},"status":{"$ref":"#/components/schemas/FileStatus","default":"uploaded"},"status_details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Details"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"},"workspace_id":{"type":"string","title":"Workspace Id","default":"default"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["id","bytes","created_at","filename"],"title":"FileObject"},"FileStatus":{"type":"string","enum":["uploaded","parsed","indexed","upload_failed","parse_failed","index_failed","parsing","indexing"],"title":"FileStatus"},"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files":{"get":{"summary":"List Files","description":"Returns a list of files, filtered by the organization.","operationId":"list_files_files_get","parameters":[{"name":"workspace","in":"query","required":false,"schema":{"type":"string","description":"List files in workspace","default":"default","title":"Workspace"},"description":"List files in workspace"},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination","title":"After"},"description":"Cursor for pagination"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":10000,"minimum":1,"description":"Limit the number of returned files","default":10000,"title":"Limit"},"description":"Limit the number of returned files"},{"name":"order","in":"query","required":false,"schema":{"type":"string","description":"Sort order by creation timestamp","default":"desc","title":"Order"},"description":"Sort order by creation timestamp"},{"name":"purpose","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FilePurpose"},{"type":"null"}],"description":"Filter by purpose","title":"Purpose"},"description":"Filter by purpose"},{"name":"filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by metadata","title":"Filter"},"description":"Filter by metadata"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Retrieve File

> Returns information about a specific file, verifying organization access.

```json
{"openapi":"3.1.0","info":{"title":"Activeloop Deep Research API","version":"1.0.0"},"servers":[{"url":"https://api.activeloop.ai","description":"Production server"},{"url":"https://api-beta.activeloop.dev","description":"Beta server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your bearer token in the format 'your-token' (without quotes or 'Bearer' prefix)"}},"schemas":{"FileObject":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","title":"Object","default":"file"},"bytes":{"type":"integer","title":"Bytes"},"created_at":{"type":"integer","title":"Created At"},"filename":{"type":"string","title":"Filename"},"purpose":{"anyOf":[{"$ref":"#/components/schemas/FilePurpose"},{"type":"null"}],"default":"user_data"},"status":{"$ref":"#/components/schemas/FileStatus","default":"uploaded"},"status_details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Details"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"},"workspace_id":{"type":"string","title":"Workspace Id","default":"default"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["id","bytes","created_at","filename"],"title":"FileObject"},"FilePurpose":{"type":"string","enum":["batch","batch_output","vision","user_data","evals"],"title":"FilePurpose"},"FileStatus":{"type":"string","enum":["uploaded","parsed","indexed","upload_failed","parse_failed","index_failed","parsing","indexing"],"title":"FileStatus"},"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/{file_id}":{"get":{"summary":"Retrieve File","description":"Returns information about a specific file, verifying organization access.","operationId":"retrieve_file_files__file_id__get","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","description":"The ID of the file","title":"File Id"},"description":"The ID of the file"},{"name":"workspace","in":"query","required":false,"schema":{"type":"string","description":"Get file from workspace","default":"default","title":"Workspace"},"description":"Get file from workspace"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileObject"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Delete File

> Delete a file, verifying organization access.

```json
{"openapi":"3.1.0","info":{"title":"Activeloop Deep Research API","version":"1.0.0"},"servers":[{"url":"https://api.activeloop.ai","description":"Production server"},{"url":"https://api-beta.activeloop.dev","description":"Beta server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your bearer token in the format 'your-token' (without quotes or 'Bearer' prefix)"}},"schemas":{"DeletedStatus":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","title":"Object","default":"file"},"deleted":{"type":"boolean","title":"Deleted","default":true}},"type":"object","required":["id"],"title":"DeletedStatus"},"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/{file_id}":{"delete":{"summary":"Delete File","description":"Delete a file, verifying organization access.","operationId":"delete_file_files__file_id__delete","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","description":"The ID of the file","title":"File Id"},"description":"The ID of the file"},{"name":"workspace","in":"query","required":false,"schema":{"type":"string","description":"Delete file from workspace","default":"default","title":"Workspace"},"description":"Delete file from workspace"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Retrieve File Content

> Returns the contents of the specified file, verifying organization access.

```json
{"openapi":"3.1.0","info":{"title":"Activeloop Deep Research API","version":"1.0.0"},"servers":[{"url":"https://api.activeloop.ai","description":"Production server"},{"url":"https://api-beta.activeloop.dev","description":"Beta server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your bearer token in the format 'your-token' (without quotes or 'Bearer' prefix)"}},"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/{file_id}/content":{"get":{"summary":"Retrieve File Content","description":"Returns the contents of the specified file, verifying organization access.","operationId":"retrieve_file_content_files__file_id__content_get","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","description":"The ID of the file","title":"File Id"},"description":"The ID of the file"},{"name":"workspace","in":"query","required":false,"schema":{"type":"string","description":"The workspace id to get file content from","default":"default","title":"Workspace"},"description":"The workspace id to get file content from"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update File Metadata

> Update metadata for a specific file, verifying organization access.

```json
{"openapi":"3.1.0","info":{"title":"Activeloop Deep Research API","version":"1.0.0"},"servers":[{"url":"https://api.activeloop.ai","description":"Production server"},{"url":"https://api-beta.activeloop.dev","description":"Beta server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter your bearer token in the format 'your-token' (without quotes or 'Bearer' prefix)"}},"schemas":{"FileObject":{"properties":{"id":{"type":"string","title":"Id"},"object":{"type":"string","title":"Object","default":"file"},"bytes":{"type":"integer","title":"Bytes"},"created_at":{"type":"integer","title":"Created At"},"filename":{"type":"string","title":"Filename"},"purpose":{"anyOf":[{"$ref":"#/components/schemas/FilePurpose"},{"type":"null"}],"default":"user_data"},"status":{"$ref":"#/components/schemas/FileStatus","default":"uploaded"},"status_details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Details"},"expires_at":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires At"},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id"},"workspace_id":{"type":"string","title":"Workspace Id","default":"default"},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["id","bytes","created_at","filename"],"title":"FileObject"},"FilePurpose":{"type":"string","enum":["batch","batch_output","vision","user_data","evals"],"title":"FilePurpose"},"FileStatus":{"type":"string","enum":["uploaded","parsed","indexed","upload_failed","parse_failed","index_failed","parsing","indexing"],"title":"FileStatus"},"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"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/files/{file_id}/metadata":{"patch":{"summary":"Update File Metadata","description":"Update metadata for a specific file, verifying organization access.","operationId":"update_file_metadata_files__file_id__metadata_patch","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","description":"The ID of the file","title":"File Id"},"description":"The ID of the file"},{"name":"workspace","in":"query","required":false,"schema":{"type":"string","description":"The workspace id to update th file in","default":"default","title":"Workspace"},"description":"The workspace id to update th file in"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"The metadata to update. `instructions` key is considered as an instruction to update metadata by AI.","title":"Metadata"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/FileObject"},{"type":"null"}],"title":"Response Update File Metadata Files  File Id  Metadata Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```