Publish a skill version from a bundle upload

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/skills/{skillId}/versions/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'base_skill_version_id=<string>' \
  --form bundle='@example-file' \
  --form 'display_title=<string>' \
  --form 'metadata=<string>'

import requests

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

files = { "bundle": ("example-file", open("example-file", "rb")) }
payload = {
    "base_skill_version_id": "<string>",
    "display_title": "<string>",
    "metadata": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('base_skill_version_id', '<string>');
form.append('bundle', '<string>');
form.append('display_title', '<string>');
form.append('metadata', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.recursion.labelbox.com/managed-agents/v1/skills/{skillId}/versions/upload', 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/{skillId}/versions/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$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/{skillId}/versions/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

	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/{skillId}/versions/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "name": "<string>",
  "organization_id": "<string>",
  "skill_id": "<string>",
  "skill_version_id": "<string>",
  "version_number": 0,
  "artifact_sha256": "<string>",
  "bundle": {
    "bytes": 0,
    "sha256": "<string>",
    "entries": [
      {
        "bytes": 0,
        "mode": 4503599627370495,
        "path": "<string>",
        "sha256": "<string>"
      }
    ]
  },
  "created_by": "<string>",
  "entrypoint_path": "<string>",
  "file_manifest": [
    "<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": "managed_agents_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 bundle upload

Mints a new immutable version from a zipped skill directory and returns it. Send the archive as the bundle part of a multipart/form-data body. 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. Every field is full content, so omitted display_title or metadata is cleared rather than kept. Filing is not published here: skill_group_id is rejected rather than ignored. 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

upload

Publish a skill version from a bundle upload

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/skills/{skillId}/versions/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'base_skill_version_id=<string>' \
  --form bundle='@example-file' \
  --form 'display_title=<string>' \
  --form 'metadata=<string>'

import requests

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

files = { "bundle": ("example-file", open("example-file", "rb")) }
payload = {
    "base_skill_version_id": "<string>",
    "display_title": "<string>",
    "metadata": "<string>"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('base_skill_version_id', '<string>');
form.append('bundle', '<string>');
form.append('display_title', '<string>');
form.append('metadata', '<string>');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.recursion.labelbox.com/managed-agents/v1/skills/{skillId}/versions/upload', 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/{skillId}/versions/upload",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$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/{skillId}/versions/upload"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

	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/{skillId}/versions/upload")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"base_skill_version_id\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"bundle\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"display_title\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"metadata\"\r\n\r\n<string>\r\n-----011000010111000001101001--"

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

{
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "name": "<string>",
  "organization_id": "<string>",
  "skill_id": "<string>",
  "skill_version_id": "<string>",
  "version_number": 0,
  "artifact_sha256": "<string>",
  "bundle": {
    "bytes": 0,
    "sha256": "<string>",
    "entries": [
      {
        "bytes": 0,
        "mode": 4503599627370495,
        "path": "<string>",
        "sha256": "<string>"
      }
    ]
  },
  "created_by": "<string>",
  "entrypoint_path": "<string>",
  "file_manifest": [
    "<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": "managed_agents_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

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

multipart/form-data

Request body for publishing a skill version by uploading a zipped skill directory in the bundle part, plus the base version it advances from. Replaces every file in the skill: parts left out are cleared, not inherited from the current version.

base_skill_version_id

string

required

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

bundle

file

required

A zipped Agent Skills directory containing a root SKILL.md and optional executable helpers, references, and assets.

display_title

string

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

metadata

string

Caller-owned key/value data as a JSON object, since a form part cannot carry structure. Rejected rather than dropped when it does not parse.

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.

Required range: -9007199254740991 <= x <= 9007199254740991

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

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 skill version from a bundle upload

Authorizations

Headers

Path Parameters

Body

Response