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

# Files

Upload files to an agent. Requires `files` scope.

## Upload a file to an agent

> Uploads a file to the agent's knowledge base. Requires \`files\` scope.\
> The agent must be running.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Files","description":"Upload files to an agent. Requires `files` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/files":{"post":{"tags":["Files"],"summary":"Upload a file to an agent","description":"Uploads a file to the agent's knowledge base. Requires `files` scope.\nThe agent must be running.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filename","content","mimeType"],"properties":{"filename":{"type":"string","maxLength":255},"content":{"type":"string"},"mimeType":{"type":"string","maxLength":100}}}}}},"responses":{"200":{"description":"File uploaded"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```
