POST /api/v1/files

File Upload & Retrieval

Upload files to use in task blocks (images, PDFs, downloads).

Upload a File

curl -X POST https://your-instance/api/v1/files \
  -H "Authorization: Bearer htk_..." \
  -F "file=@screenshot.png" \
  -F "folder=screenshots"

Required scope: tasks:create

Request (multipart/form-data)

Field	Type	Required	Description
`file`	File	Yes	The file to upload
`folder`	string	No	Folder for organization (auto-generated if omitted)

Response

{
	"url": "https://s3-bucket.../orgId/screenshots/uuid-screenshot.png",
	"key": "orgId/screenshots/uuid-screenshot.png",
	"name": "screenshot.png",
	"size": 245760,
	"type": "image/png"
}

Using Uploaded Files in Tasks

Use the returned url in task block definitions:

{
	"type": "image",
	"url": "https://s3-bucket.../orgId/screenshots/uuid-screenshot.png",
	"alt": "Deployment screenshot"
}

Or for downloads:

{
	"type": "download",
	"downloads": [
		{
			"url": "https://s3-bucket.../orgId/reports/uuid-report.pdf",
			"filename": "report.pdf",
			"size": 1048576,
			"mime_type": "application/pdf"
		}
	]
}

Storage

Files are stored in S3, organized by organization ID and folder:

{orgId}/{folder}/{uuid}-{original-filename}

Files are isolated by organization — tokens can only access files belonging to their org.