Upload a bundled file

Create a file record and get a presigned URL for direct upload to cloud storage.

Two-step upload process:

1. Call this endpoint to register the file and get a presigned URL
2. PUT the file content directly to the returned uploadUrl

Limits:

• Maximum 20 files per skill
• File names are sanitized to prevent path traversal
• Duplicate file names within a skill are rejected

POST /skills/files

Upload a bundled file

cURL

curl --request POST \
  --url https://asteragents.com/api/skills/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "skillId": 123,
  "fileName": "scripts/generate_report.py",
  "contentType": "text/x-python",
  "fileSize": 123
}
'

201

{
  "success": true,
  "file": {
    "id": 5,
    "fileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "fileName": "scripts/generate_report.py",
    "contentType": "text/x-python"
  },
  "uploadUrl": "https://example.r2.cloudflarestorage.com/..."
}

Authorizations

Authorization · string · header · required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Body

application/json

skillId · integer · required

The skill to attach the file to

fileName · string · required

File name, may include subdirectory (e.g., scripts/setup.py)

Example:

"scripts/generate_report.py"

contentType · string · required

MIME type of the file

Example:

"text/x-python"

fileSize · integer | null

File size in bytes (optional)

Response

201

application/json

File record created with presigned upload URL

success · boolean

file · object

Show child attributes

uploadUrl · string<uri>

Presigned URL for direct file upload (PUT). Expires in 10 minutes.