> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. 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 managedAgentsUpdateSkill, 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. ## OpenAPI ````yaml /managed-agents/openapi.yaml post /managed-agents/v1/skills/{skill_id}/versions openapi: 3.1.0 info: title: Managed Agents API version: 0.14.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/skills/{skill_id}/versions: post: tags: - Skills summary: Publish a skill version from a document description: >- 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. 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 managedAgentsUpdateSkill, 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. operationId: managedAgentsCreateSkillVersion parameters: - description: >- Skill id (UUID) as returned by managedAgentsCreateSkill or managedAgentsListSkills. in: path name: skill_id required: true schema: description: >- Skill id (UUID) as returned by managedAgentsCreateSkill or managedAgentsListSkills. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateSkillVersionRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/SkillVersion' description: >- 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. headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_json - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '409': description: Conflict. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' - $ref: '#/components/schemas/ManagedAgentsApiErrorRevisionConflict' discriminator: propertyName: code mapping: conflict: $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' revision_conflict: $ref: >- #/components/schemas/ManagedAgentsApiErrorRevisionConflict x-recursion-error-codes: - conflict - revision_conflict headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorSkillStorageUnconfigured discriminator: propertyName: code mapping: managed_agents_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable skill_storage_unconfigured: $ref: >- #/components/schemas/ManagedAgentsApiErrorSkillStorageUnconfigured x-recursion-error-codes: - managed_agents_unavailable - service_unavailable - skill_storage_unconfigured headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- 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`. schema: type: string minLength: 1 schemas: CreateSkillVersionRequest: description: >- Request body for creating a new immutable skill version. Every field means what it means on managedAgentsCreateSkill -- 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. properties: base_skill_version_id: description: >- 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. format: uuid type: string display_title: description: Human-readable title for listings. Defaults to the frontmatter name. type: string document: description: >- 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. type: string manifest: description: >- Relative paths of files bundled with the skill, listed to the model when it activates the skill. Paths must stay inside the skill directory. items: type: string type: array metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Caller-owned key/value data stored with the skill and returned unchanged. type: object required: - document - base_skill_version_id type: object additionalProperties: false SkillVersion: description: >- 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. properties: artifact_sha256: description: SHA-256 checksum of the stored document. type: string bundle: $ref: '#/components/schemas/SkillBundle' description: >- The files bundled with this version, and the archive they are mounted from. Absent for a version that carries only a document. created_at: description: Server-assigned RFC 3339 timestamp of when this version was minted. format: date-time type: string created_by: description: Identifier of the caller that minted this version. type: string description: description: The skill's routing description as it stood at this version. type: string entrypoint_path: description: >- Path of the document within the bundle. SKILL.md unless the author moved it. type: string file_manifest: description: >- Relative paths of files bundled with the skill. Listed to the model at activation; read only if it uses them. items: type: string type: array frontmatter: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- The parsed SKILL.md frontmatter as authored, including fields this platform does not interpret. type: object instructions: description: >- The skill's full Markdown instructions. Returned only when reading a single version, since a listing has no use for it. type: string metadata: additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Caller-owned key/value data stored with this version and returned unchanged. type: object name: description: The skill's addressable name as it stood at this version. type: string organization_id: description: >- Organization that owns this record. Resolved from the API key; never accepted from the caller. type: string skill_id: description: Skill this version belongs to. type: string skill_version_id: description: >- Identifier for this skill version. Server-assigned. Pass it when attaching a skill that must stay pinned to a specific revision. type: string version_number: description: >- Monotonically increasing version counter within the skill, starting at 1. Server-assigned. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - organization_id - skill_id - skill_version_id - version_number - name - description - created_at type: object additionalProperties: false ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRevisionConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - revision_conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorSkillStorageUnconfigured: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - skill_storage_unconfigured message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object SkillBundle: description: >- 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. properties: bytes: description: >- Compressed size of the archive in bytes, which is what mounting this skill into a session costs to transfer. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 entries: description: Every file in the bundle, sorted by path. items: $ref: '#/components/schemas/SkillBundleEntry' type: array sha256: description: >- SHA-256 checksum of the canonical archive; uploads of identical files have the same value. type: string required: - sha256 - bytes type: object additionalProperties: false ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. SkillBundleEntry: description: >- One file inside a skill version's bundle, listed so a caller can see what a version ships, and what of it the sandbox will be able to run, without downloading the archive. properties: bytes: description: Size of the file in bytes. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 mode: description: >- Permission bits assigned by the platform based on whether the bundled file is executable; never taken from the uploaded archive. minimum: 0 type: integer maximum: 9007199254740991 path: description: >- Path of the file relative to the skill directory, for example an executable helper named tag.sh. type: string sha256: description: >- SHA-256 of the file's contents. Stable across repacking, so comparing two versions' entries decides which files were added, removed, or changed without downloading either bundle. type: string required: - path - bytes - sha256 - mode type: object additionalProperties: false headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````