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

# Agent Files

## Upload agent file

> This endpoint uploads an agent file associated with the provided API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"UploadAgentFileBodyDTO":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload"},"autoAddToVectorStore":{"type":"boolean","description":"Indicates whether to automatically add the file to the vector store."}},"required":["file"]},"UploadAgentFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent file","format":"uuid"},"fileName":{"type":"string","description":"Name of the agent file"},"url":{"type":"string","description":"URL of the agent file"},"createdAt":{"type":"string","description":"Creation date of the agent file","format":"date-time"},"vectorStoreFileId":{"type":"string","description":"Unique identifier for the vector store file"},"isUploadedToVectorStore":{"type":"boolean","description":"Indicates the file’s upload status to the vector store. A null value suggests a possible vector store error.","nullable":true},"vectorStoreUploadStatus":{"type":"string","enum":["processing","done","failed"],"description":"Lifecycle status of the file upload to the OpenAI vector store. `null` means not uploaded, `processing` means an upload is in progress, `done` means the upload is complete.","nullable":true},"uploadedToVectorStoreAt":{"type":"string","description":"Date when the file was uploaded to the vector store","format":"date-time"}},"required":["id","fileName","url","createdAt"]},"BadRequestErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"name":{"type":"object","default":"BAD_REQUEST"},"message":{"type":"string","default":"INVALID_REQUEST"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-files/upload":{"post":{"description":"This endpoint uploads an agent file associated with the provided API key.","operationId":"ExternalApiAgentFilesController_uploadAgentFile","parameters":[],"requestBody":{"required":true,"description":"Upload agent file","content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadAgentFileBodyDTO"}}}},"responses":{"200":{"description":"Successfully uploaded agent file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadAgentFileResponseDTO"}}}},"400":{"description":"File is required.\n\nFailed to upload agent file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Upload agent file","tags":["Agent-files","Agent API Key"]}}}}
```

## Get agent files by API key

> This endpoint retrieves the agent files associated with the provided API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"GetAgentFilesByApiKeyResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent file","format":"uuid"},"fileName":{"type":"string","description":"Name of the agent file"},"url":{"type":"string","description":"URL of the agent file"},"createdAt":{"type":"string","description":"Creation date of the agent file","format":"date-time"},"vectorStoreFileId":{"type":"string","description":"Unique identifier for the vector store file"},"isUploadedToVectorStore":{"type":"boolean","description":"Indicates the file’s upload status to the vector store. A null value suggests a possible vector store error.","nullable":true},"vectorStoreUploadStatus":{"type":"string","enum":["processing","done","failed"],"description":"Lifecycle status of the file upload to the OpenAI vector store. `null` means not uploaded, `processing` means an upload is in progress, `done` means the upload is complete.","nullable":true},"uploadedToVectorStoreAt":{"type":"string","description":"Date when the file was uploaded to the vector store","format":"date-time"}},"required":["id","fileName","url","createdAt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-files/by-api-key":{"get":{"description":"This endpoint retrieves the agent files associated with the provided API key.","operationId":"ExternalApiAgentFilesController_getAgentFilesByApiKey","parameters":[],"responses":{"200":{"description":"Successfully retrieved agent files with details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentFilesByApiKeyResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Agent files not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get agent files by API key","tags":["Agent-files","Agent API Key"]}}}}
```

## Delete agent files by IDs

> This endpoint deletes the agent files by ids

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"DeleteAgentFilesBodyDTO":{"type":"object","properties":{"fileIds":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["fileIds"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-files":{"delete":{"description":"This endpoint deletes the agent files by ids","operationId":"ExternalApiAgentFilesController_deleteAgentFiles","parameters":[],"requestBody":{"required":true,"description":"Request body for deleting agent files.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAgentFilesBodyDTO"}}}},"responses":{"200":{"description":"Successfully deleted agent files."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Delete agent files by IDs","tags":["Agent-files","Agent API Key"]}}}}
```

## Delete agent file by ID

> This endpoint deletes the agent file by id

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-files/{id}/delete":{"delete":{"description":"This endpoint deletes the agent file by id","operationId":"ExternalApiAgentFilesController_deleteAgentFile","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the agent file to delete.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully deleted agent file."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Agent file not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Delete agent file by ID","tags":["Agent-files","Agent API Key"]}}}}
```

## Delete agent file from vector store by ID

> This endpoint deletes the agent file from vector store by id

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-files/{id}/delete-from-vector-store":{"delete":{"description":"This endpoint deletes the agent file from vector store by id","operationId":"ExternalApiAgentFilesController_deleteAgentFileFromVectorStore","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the agent file to delete from vector store.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully deleted agent file from vector store."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Agent file not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Delete agent file from vector store by ID","tags":["Agent-files","Agent API Key"]}}}}
```

## Add agent file to vector store by ID

> This endpoint adds the agent file to vector store by id

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-files/{id}/add-to-vector-store":{"put":{"description":"This endpoint adds the agent file to vector store by id","operationId":"ExternalApiAgentFilesController_addFileToVectorStore","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the agent file to add to vector store.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully added agent file to vector store."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Agent file not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Add agent file to vector store by ID","tags":["Agent-files","Agent API Key"]}}}}
```

## Add agent file to vector store asynchronously by ID

> This endpoint starts adding the agent file to the vector store and returns before processing is complete.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"EntityNotFoundErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":404},"name":{"type":"object","default":"ENTITY_NOT_FOUND_ERROR"},"message":{"type":"string","default":"ENTITY_NOT_FOUND"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-files/{id}/add-to-vector-store/async":{"put":{"description":"This endpoint starts adding the agent file to the vector store and returns before processing is complete.","operationId":"ExternalApiAgentFilesController_addFileToVectorStoreAsync","parameters":[{"name":"id","required":true,"in":"path","description":"The ID of the agent file to add to vector store.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully started adding agent file to vector store."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Agent file not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Add agent file to vector store asynchronously by ID","tags":["Agent-files","Agent API Key"]}}}}
```


---

# 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://raia2.gitbook.io/raia/api-reference/agent-files.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.