Skills

Overview

Skills package instructions and supporting files that extend Agents. Use these endpoints to upload and manage Tenant Skills or inspect platform-provided Skills before attachment.

Endpoints

POST /v1/skills

Uploads a tenant Skill as a ZIP archive. SKILL.md frontmatter is the only source of the Skill's name, description, and meta. A tenant can have at most 100 Skills.

Request

Requires bearer authentication and multipart/form-data. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.

Form field	Type	Required	Description
`file`	file	yes	ZIP with `SKILL.md` at its root
`userId`	string	no	Attribution; defaults to `""`
`metadata`	JSON string	no	JSON object; defaults to `{}`

The ZIP may be at most 3 MiB compressed and 10 MiB uncompressed, with at most 90 safe relative file paths. The Skill name must be lowercase kebab-case.

Response

Returns 201 Created with a detailed Skill object, including its live files listing.

Response schema: skillDetailSchema.

Errors

400 invalid_request for a missing/invalid archive or metadata, unsafe paths, size/file-count limits, invalid SKILL.md, duplicate name, or the Skill cap. See REST errors.

cURL

curl --request POST "$BLAZING_AGENTS_BASE_URL/v1/skills" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --form "file=@./my-skill.zip;type=application/zip" \
  --form 'metadata={"source":"internal"}'

SDK: create. See Skills and Create and attach a Skill.

GET /v1/skills

Returns platform and/or tenant Skills. The bounded list is not paginated and list items omit meta and files.

Request

Requires bearer authentication. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.

Query parameter	Type	Default	Description
`filter`	string	`all`	`all`, `built-in`, or `my`
`userId`	string	—	Attribution filter for tenant Skills; ignored for `built-in`

Response

Returns 200 OK with { "skills": [<Skill list item>] }. See Skill objects.

Response schema: skillsResponseSchema.

Errors

400 invalid_request for an invalid filter. See REST errors.

cURL

curl --get "$BLAZING_AGENTS_BASE_URL/v1/skills" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --data-urlencode "filter=all"

SDK: list. See Skills and Create and attach a Skill.

GET /v1/skills/:skillId

Returns one tenant or platform Skill and its file manifest. Reading a Skill does not attach it to an Agent or change its lifecycle.

Requires bearer authentication and a tenant or platform skillId. There are no query or body parameters. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.
Path	`skillId`	yes	Tenant or platform Skill ID.

Response

Returns 200 OK with the detailed Skill object. Tenant Skills include { path, sizeBytes } entries in files; platform Skills return files: [].

Response schema: skillResponseSchema.

{
  "id": "skill_1234567890ABCDEF",
  "ownerKind": "tenant",
  "tenantId": "ten_1234567890ABCDEF",
  "name": "support-playbook",
  "description": "Resolve common support cases.",
  "userId": "",
  "metadata": {},
  "createdAt": "2026-07-10T10:00:00Z",
  "updatedAt": "2026-07-10T10:00:00Z",
  "meta": { "version": 1 },
  "files": [{ "path": "SKILL.md", "sizeBytes": 820 }]
}

Errors

400 invalid_request for a malformed ID. 404 not_found for a missing or foreign tenant Skill. See REST errors.

cURL

curl "$BLAZING_AGENTS_BASE_URL/v1/skills/skill_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: get. See Skills and Create and attach a Skill.

PUT /v1/skills/:skillId

Uploads and validates a complete immutable tenant Skill version, then atomically switches the Skill record to it. API and task-worker readers never observe a partial version; obsolete private Storage prefixes are reclaimed by durable idempotent cleanup. userId remains immutable. Platform Skills cannot be updated through /v1.

Request

Requires bearer authentication, a tenant skillId, and multipart/form-data. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.
Path	`skillId`	yes	Tenant or platform Skill ID.

Form field	Type	Required	Description
`file`	file	yes	Replacement Skill ZIP
`metadata`	JSON string	no	Replacement metadata; omit to keep existing metadata

The archive follows the same limits as Create a Skill.

Response

Returns 200 OK with the complete updated Skill object.

Response schema: skillDetailSchema.

Errors

400 invalid_request for invalid archive/metadata, duplicate name, or a platform Skill. 404 not_found when a tenant Skill is missing or foreign. See REST errors.

cURL

curl --request PUT \
  "$BLAZING_AGENTS_BASE_URL/v1/skills/skill_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY" \
  --form "file=@./my-skill.zip;type=application/zip"

SDK: update. See Skills and Create and attach a Skill.

DELETE /v1/skills/:skillId

Deletes a tenant Skill. Detach it from every Agent first. Platform Skills cannot be deleted through /v1.

Request

Requires bearer authentication and a skillId path parameter. There are no query or body parameters. The credential selects the Tenant ownership boundary; reads and mutations are restricted to resources owned by that Tenant.

Location	Field	Required	Description
Header	`Authorization`	yes	Tenant API key or dashboard Supabase JWT.
Path	`skillId`	yes	Tenant or platform Skill ID.

curl --request DELETE \
  "$BLAZING_AGENTS_BASE_URL/v1/skills/skill_1234567890ABCDEF" \
  --header "Authorization: Bearer $BLAZING_AGENTS_API_KEY"

SDK: delete. See Skills and Create and attach a Skill.

On this page