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

# Files

Upload files securely for use in automation workflows.

## Upload File

> Create a secure file upload target with detailed upload instructions. Returns a presigned URL and form fields for direct S3 upload.

```json
{"openapi":"3.1.0","info":{"title":"Kognitos REST API v2","version":"2.0.0"},"tags":[{"description":"Upload files securely for use in automation workflows.","name":"files"}],"servers":[{"description":"US Region","url":"https://rest-api.app.kognitos.com/v2"},{"description":"EU Region","url":"https://rest-api.eu.kognitos.com/v2"},{"description":"UK Region","url":"https://rest-api.uk.kognitos.com/v2"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{"APIKeyHeader":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"CreateFileRequest":{"properties":{"agent_id":{"description":"The ID of the agent in which this file will be used; may be omitted if the API token is scoped to an agent (rather than the organization).","maxLength":26,"minLength":1,"pattern":"^[a-zA-Z0-9-_]+$","title":"Agent Id","type":"string"},"file_name":{"description":"The name of the file to be uploaded.","maxLength":256,"minLength":1,"title":"File Name","type":"string"}},"required":["file_name"],"title":"CreateFileRequest","type":"object"},"FileResource":{"description":"File upload response containing S3 presigned POST credentials.\n\nUse these fields to upload your file directly to S3:\n1. POST to upload_url with multipart/form-data\n2. Include all upload_fields as form fields\n3. Add your file as 'file' field\n4. Use the returned id to reference this file in other API calls","properties":{"file_name":{"description":"The sanitized filename that will be used for storage","title":"File Name","type":"string"},"id":{"description":"Unique file identifier - use this ID when referencing the file in other API calls (like starting a run). Only available after successful upload.","title":"Id","type":"string"},"upload_fields":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"description":"S3 authentication fields - include ALL of these as form fields in your multipart upload request. These contain the signature, policy, and other S3 authentication data.","title":"Upload Fields"},"upload_http_headers":{"additionalProperties":{"type":"string"},"description":"HTTP headers for upload request (usually empty for S3 multipart uploads)","title":"Upload Http Headers","type":"object"},"upload_http_method":{"$ref":"#/components/schemas/FileUploadHttpMethod","default":"POST","description":"HTTP method for upload - always POST for S3 presigned uploads"},"upload_url":{"description":"S3 presigned POST URL where you upload your file. POST your multipart/form-data request to this URL.","title":"Upload Url","type":"string"}},"required":["id","file_name","upload_url"],"title":"FileResource","type":"object"},"FileUploadHttpMethod":{"description":"Valid HTTP method for file upload","enum":["PUT","POST"],"title":"FileUploadHttpMethod","type":"string"},"ErrorModel":{"properties":{"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},{"type":"null"}],"description":"An optional list of details about the error","title":"Details"},"message":{"description":"Error message","title":"Message","type":"string"},"status_code":{"description":"HTTP status code corresponding to the error","title":"Status Code","type":"integer"}},"required":["status_code","message"],"title":"ErrorModel","type":"object"},"ErrorDetail":{"properties":{"name":{"description":"Name of the error detail","title":"Name","type":"string"},"value":{"$ref":"#/components/schemas/ErrorDetailType","description":"Value of the error detail"}},"required":["name","value"],"title":"ErrorDetail","type":"object"},"ErrorDetailType":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"}]}}},"paths":{"/files":{"post":{"description":"Create a secure file upload target with detailed upload instructions. Returns a presigned URL and form fields for direct S3 upload.","operationId":"create_file_upload","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFileRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileResource"}}},"description":"The file upload created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"Invalid input values"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorModel"}}},"description":"The specified agent was not found"}},"summary":"Upload File","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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/rest-api/v2/files.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.