Publish a new version of a skill

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base_skill_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "display_title": "example",
  "document": "example",
  "manifest": [
    "example"
  ],
  "metadata": {
    "key": "example"
  }
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions"

payload = {
    "base_skill_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "display_title": "example",
    "document": "example",
    "manifest": ["example"],
    "metadata": { "key": "example" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    base_skill_version_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
    display_title: 'example',
    document: 'example',
    manifest: ['example'],
    metadata: {key: 'example'}
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'base_skill_version_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
    'display_title' => 'example',
    'document' => 'example',
    'manifest' => [
        'example'
    ],
    'metadata' => [
        'key' => 'example'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions"

	payload := strings.NewReader("{\n  \"base_skill_version_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n  \"display_title\": \"example\",\n  \"document\": \"example\",\n  \"manifest\": [\n    \"example\"\n  ],\n  \"metadata\": {\n    \"key\": \"example\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"base_skill_version_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n  \"display_title\": \"example\",\n  \"document\": \"example\",\n  \"manifest\": [\n    \"example\"\n  ],\n  \"metadata\": {\n    \"key\": \"example\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"base_skill_version_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n  \"display_title\": \"example\",\n  \"document\": \"example\",\n  \"manifest\": [\n    \"example\"\n  ],\n  \"metadata\": {\n    \"key\": \"example\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "artifact_sha256": "example",
  "bundle": {
    "bytes": 1,
    "entries": [
      {
        "bytes": 1,
        "mode": 1,
        "path": "example",
        "sha256": "example"
      }
    ],
    "sha256": "example"
  },
  "created_at": "2026-02-18T09:30:00.000Z",
  "created_by": "example",
  "description": "example",
  "entrypoint_path": "example",
  "file_manifest": [
    "example"
  ],
  "frontmatter": {
    "key": "example"
  },
  "instructions": "example",
  "metadata": {
    "key": "example"
  },
  "name": "example-name",
  "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "skill_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "skill_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "version_number": 1
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

Skills

Publish a new version of a skill

Mints a new immutable version from an uploaded zip or a SKILL.md document and returns it, because an author who just published needs the version id to pin an agent to it. Sessions already running keep the version they froze. base_skill_version_id must be the skill’s current latest_skill_version_id or the request is rejected with 409 revision_conflict, so the caller can re-read and retry rather than silently racing another writer. Every field is full content, there is no partial-update or omit-to-inherit semantics, so an omitted display_title or metadata is cleared rather than kept. Filing is not published here — a skill keeps the group it is in, and skill_group_id is rejected rather than ignored; move a skill between groups with updateSkill, which refiles without minting a version.

POST

managed-agents

skills

{skill_id}

versions

Publish a new version of a skill

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base_skill_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "display_title": "example",
  "document": "example",
  "manifest": [
    "example"
  ],
  "metadata": {
    "key": "example"
  }
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions"

payload = {
    "base_skill_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
    "display_title": "example",
    "document": "example",
    "manifest": ["example"],
    "metadata": { "key": "example" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    base_skill_version_id: '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
    display_title: 'example',
    document: 'example',
    manifest: ['example'],
    metadata: {key: 'example'}
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'base_skill_version_id' => '9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d',
    'display_title' => 'example',
    'document' => 'example',
    'manifest' => [
        'example'
    ],
    'metadata' => [
        'key' => 'example'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions"

	payload := strings.NewReader("{\n  \"base_skill_version_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n  \"display_title\": \"example\",\n  \"document\": \"example\",\n  \"manifest\": [\n    \"example\"\n  ],\n  \"metadata\": {\n    \"key\": \"example\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"base_skill_version_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n  \"display_title\": \"example\",\n  \"document\": \"example\",\n  \"manifest\": [\n    \"example\"\n  ],\n  \"metadata\": {\n    \"key\": \"example\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/skills/{skill_id}/versions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"base_skill_version_id\": \"9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d\",\n  \"display_title\": \"example\",\n  \"document\": \"example\",\n  \"manifest\": [\n    \"example\"\n  ],\n  \"metadata\": {\n    \"key\": \"example\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "artifact_sha256": "example",
  "bundle": {
    "bytes": 1,
    "entries": [
      {
        "bytes": 1,
        "mode": 1,
        "path": "example",
        "sha256": "example"
      }
    ],
    "sha256": "example"
  },
  "created_at": "2026-02-18T09:30:00.000Z",
  "created_by": "example",
  "description": "example",
  "entrypoint_path": "example",
  "file_manifest": [
    "example"
  ],
  "frontmatter": {
    "key": "example"
  },
  "instructions": "example",
  "metadata": {
    "key": "example"
  },
  "name": "example-name",
  "organization_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "skill_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "skill_version_id": "9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "version_number": 1
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {}
}

{
  "code": "analytics",
  "message": "<string>",
  "details": {}
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

A Recursion API key, created in the console under API keys.

Path Parameters

skill_id

string<uuid>

required

Skill id (UUID) as returned by createSkill or listSkills.

Body

Request body for creating a new immutable skill version. Every field means what it means on createSkill -- full content is always required, there is no partial update. base_skill_version_id must be the skill's current version or the request is rejected with revision_conflict so the caller can re-read and retry.

base_skill_version_id

string<uuid>

required

The skill's current latest_skill_version_id, as returned by getSkill. Rejected with 409 revision_conflict if the skill has moved past this version.

document

string

required

The complete SKILL.md: YAML frontmatter delimited by --- on the very first line, then Markdown instructions. name and description are required in the frontmatter and are read from it.

display_title

string

Human-readable title for listings. Defaults to the frontmatter name.

manifest

string[]

Relative paths of files bundled with the skill, listed to the model when it activates the skill. Paths must stay inside the skill directory.

metadata

object

Caller-owned key/value data stored with the skill and returned unchanged.

Show child attributes

Response

An immutable snapshot of a skill's document and metadata, minted on every update. An agent may pin one, so that what a session runs cannot change under it.

created_at

string<date-time>

required

Server-assigned RFC 3339 timestamp of when this version was minted.

description

string

required

The skill's routing description as it stood at this version.

name

string

required

The skill's addressable name as it stood at this version.

organization_id

string

required

Organization that owns this record. Resolved from the API key; never accepted from the caller.

skill_id

string

required

Skill this version belongs to.

skill_version_id

string

required

Identifier for this skill version. Server-assigned. Pass it when attaching a skill that must stay pinned to a specific revision.

version_number

integer<int64>

required

Monotonically increasing version counter within the skill, starting at 1. Server-assigned.

artifact_sha256

string

SHA-256 checksum of the stored document.

bundle

object

The files bundled with this version, and the archive they are mounted from. Absent for a version that carries only a document.

Show child attributes

Example:

{
  "bytes": 1,
  "entries": [
    {
      "bytes": 1,
      "mode": 1,
      "path": "example",
      "sha256": "example"
    }
  ],
  "sha256": "example"
}

created_by

string

Identifier of the caller that minted this version.

entrypoint_path

string

Path of the document within the bundle. SKILL.md unless the author moved it.

file_manifest

string[]

Relative paths of files bundled with the skill. Listed to the model at activation; read only if it uses them.

frontmatter

object

The parsed SKILL.md frontmatter as authored, including fields this platform does not interpret.

Show child attributes

instructions

string

The skill's full Markdown instructions. Returned only when reading a single version, since a listing has no use for it.

metadata

object

Caller-owned key/value data stored with this version and returned unchanged.

Show child attributes

API reference

Endpoints

Publish a new version of a skill

Authorizations

Path Parameters

Body

Response