Skills HTTP API

Upload skill folders to Evolve, then attach their returned upload:<id> references to a job’s agent arms. These uploads are the skills an evaluated agent receives, separate from the CLI’s documentation skill. Examples reuse connection setup. Create skill.tar.gz from a skill folder containing SKILL.md, with that file at the archive root:

curl -sS "$API/api/skills" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -F 'archive=@skill.tar.gz' \
  -F 'name=my-skill'

Success returns 201 with { "skills": [...] }, containing one or more SkillUpload records. Use a returned id, not the folder name, in an upload:<id> reference.

Routes

Method and path	Input	Success
`POST /api/skills`	Multipart fields below	`201`, object with a `skills` array
`GET /api/skills`	Optional `scope`, `limit`, `cursor`, `sortField`, `sortDirection`	`200 SkillUploadPage`
`GET /api/skills/{id}`	Upload id or `name:<skill-name>`	`200 SkillUpload` plus `skill_md`
`DELETE /api/skills/{id}`	Returned upload id	`204`, no body

scope is my (default), shared, or org. sortField accepts name, size, or uploaded; sortDirection accepts asc or desc. Keep sorting unchanged while paging.

Upload fields

Multipart field	Required	Meaning
`archive`	Yes	Gzipped skill folder or directory of skill folders
`name`	For a root skill	Required when `SKILL.md` is at the archive root; ignored when child folders name the skills
`org`	No	Organization slug or id; requires membership; defaults to your personal organization

name accepts letters, digits, ., _, and -, up to 100 characters. For multiple skills, put each skill in its own top-level folder with its own SKILL.md. Uploading the same name and content reuses its record. Different content under the same name creates a new record and makes it the current name:<skill-name> reference. Existing upload:<id> references remain fixed. An existing identical record cannot be moved to another organization by reuploading it with a different org.

Read and remove

Set SKILL_ID from an upload or list response:

curl -sS "$API/api/skills/$SKILL_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

The response includes metadata and skill_md, which is null when the text cannot be read. See skill methods for the metadata fields. GET also accepts name:my-skill to read your current upload for that name. Name lookup is limited to your own skills; organization members can read shared records by upload id.

curl -sS -X DELETE "$API/api/skills/$SKILL_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

Only the creator can delete an upload, and DELETE requires its record id, not a name reference. A QUEUED, RUNNING, or CANCELLING job referencing the upload prevents deletion with 409 skill_in_use. Wait for that job to finish, or cancel it and wait until it settles. For an agent arm, add the reference to its skills array:

{
  "name": "codex",
  "model_name": "gpt-6-luna",
  "skills": ["upload:YOUR_SKILL_ID"]
}

This is an arm fragment, not a complete job request. Replace YOUR_SKILL_ID, then include the arm in job creation.

Errors

Invalid archives, missing skill files, or an unsupported name are refused. Unknown upload ids return 404 skill_not_found. Consult the skill error codes and use GET /api/meta for current upload limits.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Skills HTTP API

Routes

Upload fields

Read and remove

Errors