Publish a skill version from a document

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v2/skills/{skillId}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "baseSkillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "document": "<string>",
  "displayTitle": "<string>",
  "manifest": [
    "<string>"
  ],
  "metadata": {}
}
'

import requests

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

payload = {
    "baseSkillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "document": "<string>",
    "displayTitle": "<string>",
    "manifest": ["<string>"],
    "metadata": {}
}
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({
    baseSkillVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    document: '<string>',
    displayTitle: '<string>',
    manifest: ['<string>'],
    metadata: {}
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/skills/{skillId}/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/v2/skills/{skillId}/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([
    'baseSkillVersionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'document' => '<string>',
    'displayTitle' => '<string>',
    'manifest' => [
        '<string>'
    ],
    'metadata' => [
        
    ]
  ]),
  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/v2/skills/{skillId}/versions"

	payload := strings.NewReader("{\n  \"baseSkillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"document\": \"<string>\",\n  \"displayTitle\": \"<string>\",\n  \"manifest\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\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/v2/skills/{skillId}/versions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"baseSkillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"document\": \"<string>\",\n  \"displayTitle\": \"<string>\",\n  \"manifest\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/skills/{skillId}/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  \"baseSkillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"document\": \"<string>\",\n  \"displayTitle\": \"<string>\",\n  \"manifest\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}"

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

{
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "name": "<string>",
  "organizationId": "<string>",
  "skillId": "<string>",
  "skillVersionId": "<string>",
  "versionNumber": 0,
  "artifactSha256": "<string>",
  "bundle": {
    "bytes": 0,
    "sha256": "<string>",
    "entries": [
      {
        "bytes": 0,
        "mode": 4503599627370495,
        "path": "<string>",
        "sha256": "<string>"
      }
    ]
  },
  "createdBy": "<string>",
  "entrypointPath": "<string>",
  "fileManifest": [
    "<string>"
  ],
  "frontmatter": {},
  "instructions": "<string>",
  "metadata": {}
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "conflict",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "payload_too_large",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "idempotency_unavailable",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Skills

Publish a skill version from a document

Mints a new immutable version from 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. baseSkillVersionId must be the skill’s current latestSkillVersionId 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 displayTitle or metadata is cleared rather than kept. Filing is not published here — a skill keeps the group it is in, and skillGroupId is rejected rather than ignored; move a skill between groups with managedAgentsUpdateSkillV2, which refiles without minting a version. Do not automatically retry an ambiguous transport failure: re-read the skill’s latest version first, because this operation does not replay a prior response.

POST

managed-agents

skills

{skillId}

versions

Publish a skill version from a document

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v2/skills/{skillId}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "baseSkillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "document": "<string>",
  "displayTitle": "<string>",
  "manifest": [
    "<string>"
  ],
  "metadata": {}
}
'

import requests

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

payload = {
    "baseSkillVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "document": "<string>",
    "displayTitle": "<string>",
    "manifest": ["<string>"],
    "metadata": {}
}
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({
    baseSkillVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    document: '<string>',
    displayTitle: '<string>',
    manifest: ['<string>'],
    metadata: {}
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/skills/{skillId}/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/v2/skills/{skillId}/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([
    'baseSkillVersionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'document' => '<string>',
    'displayTitle' => '<string>',
    'manifest' => [
        '<string>'
    ],
    'metadata' => [
        
    ]
  ]),
  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/v2/skills/{skillId}/versions"

	payload := strings.NewReader("{\n  \"baseSkillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"document\": \"<string>\",\n  \"displayTitle\": \"<string>\",\n  \"manifest\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\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/v2/skills/{skillId}/versions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"baseSkillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"document\": \"<string>\",\n  \"displayTitle\": \"<string>\",\n  \"manifest\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/skills/{skillId}/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  \"baseSkillVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"document\": \"<string>\",\n  \"displayTitle\": \"<string>\",\n  \"manifest\": [\n    \"<string>\"\n  ],\n  \"metadata\": {}\n}"

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

{
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "name": "<string>",
  "organizationId": "<string>",
  "skillId": "<string>",
  "skillVersionId": "<string>",
  "versionNumber": 0,
  "artifactSha256": "<string>",
  "bundle": {
    "bytes": 0,
    "sha256": "<string>",
    "entries": [
      {
        "bytes": 0,
        "mode": 4503599627370495,
        "path": "<string>",
        "sha256": "<string>"
      }
    ]
  },
  "createdBy": "<string>",
  "entrypointPath": "<string>",
  "fileManifest": [
    "<string>"
  ],
  "frontmatter": {},
  "instructions": "<string>",
  "metadata": {}
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "conflict",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "payload_too_large",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "idempotency_unavailable",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Authorizations

Authorization

string

header

required

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

Headers

Idempotency-Key

string

Optional replay-protection key scoped to the verified tenant, principal, operation and decoded resource path. Equivalent JSON formatting and field order use the same fingerprint. Matching retries replay the original 201 result and Location; conflicting reuse returns 409 idempotency_conflict and an active request returns 409 idempotency_in_progress. Completed receipts last approximately 24 hours and pending claims may be reclaimed after approximately 1 hour. No deduplication is guaranteed after expiry.

Required string length: 1 - 256

Pattern: ^[!-~]+$

x-tenant-id

string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1

x-organization-id

string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

skillId

string<uuid>

required

Skill id (UUID) as returned by managedAgentsCreateSkill or managedAgentsListSkills.

Body

application/json

baseSkillVersionId

string<uuid>

required

write-only

document

string

required

write-only

displayTitle

string

write-only

manifest

string[]

write-only

metadata

object

Show child attributes

Response

Created

createdAt

string<date-time>

required

read-only

description

string

required

read-only

name

string

required

read-only

organizationId

string

required

read-only

skillId

string

required

read-only

skillVersionId

string

required

read-only

versionNumber

integer<int64>

required

read-only

Required range: -9007199254740991 <= x <= 9007199254740991

artifactSha256

string

read-only

bundle

object

The files bundled with one skill version, stored as a single canonical archive and extracted into the session sandbox so the agent can read references and run scripts.

Show child attributes

createdBy

string

read-only

entrypointPath

string

read-only

fileManifest

string[]

read-only

frontmatter

object

read-only

Show child attributes

instructions

string

read-only

metadata

object

Show child attributes

API reference

Endpoints

Publish a skill version from a document

Authorizations

Headers

Path Parameters

Body

Response