{ "openapi": "3.1.0", "info": { "title": "Mindset API", "version": "v1", "description": "Call Mindset from your own systems, with no person and no AI model in the loop. Today: keep an Environment's Skills in step with the ones your system holds: list them, push each one, read it back, and delete the ones your system no longer has.\n\nEvery request carries an org API key in the `x-api-key` header. An Org admin issues keys in the console (Settings → API keys); a key choosing **Skills only** reaches the Skills routes and nothing else. A key belongs to one Environment, and every path names the Org and that Environment. Keep keys on your servers: a request from a browser has no business holding one. Paths are on the host of the Mindset instance you call.\n\nEvery call is counted against the key that made it, per route, version of the API and day.\n\nEvery refusal is a JSON object with a `code` to branch on, a `message` for a person and, where there is more to say, a `context`. One answer is not listed per operation: an unexpected failure answers 500.\n\n**What v1 promises.** Everything here is version 1, and it changes only in ways a working caller keeps working through: new routes, new optional request fields, new fields in a response, and new error codes. So a caller must ignore response fields it does not know, and treat an error code it does not know by its HTTP status. Nothing documented here is removed, renamed or narrowed within v1. A change that would break a caller is made as `/api/v2`, served beside `/api/v1`, which keeps answering through a declared deprecation window and says so in `Deprecation` and `Sunset` headers on every response." }, "security": [ { "orgApiKey": [] } ], "tags": [ { "name": "Skills", "description": "Instructions, with any text files beside them, that an agent loads when a request matches. A Skill is addressed by its handle; it has numbered versions, and at most one of them is live: the one agents load." } ], "paths": { "/api/v1/orgs/{orgSlug}/envs/{envSlug}/skills": { "get": { "operationId": "listSkills", "summary": "List the Environment's Skills", "description": "Every Skill in the key's Environment, in byte order of the handle (`-` before digits, digits before letters), each with its status, the version agents load and its newest version: enough to tell which Skills a system holds that this Environment lacks, and which it holds that the system no longer does. 50 per page unless `limit` says otherwise, at most 200; `nextCursor` continues it. A Skill created or deleted between two pages moves no other Skill between them. A deleted Skill is not listed.\n\nNeeds a key holding `skills:read`.", "tags": [ "Skills" ], "x-required-scope": "skills:read", "parameters": [ { "name": "orgSlug", "in": "path", "required": true, "description": "The Org's slug: the key's own Org.", "schema": { "type": "string", "minLength": 1 } }, { "name": "envSlug", "in": "path", "required": true, "description": "The Environment's slug: the one the key was issued into.", "schema": { "type": "string", "minLength": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Skills per page. Default 50; a larger number reads 200, and the answer's limitClamped says so.", "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Skills per page. Default 50; a larger number reads 200, and the answer's limitClamped says so." } }, { "name": "cursor", "in": "query", "required": false, "description": "The nextCursor of the page before, passed back unchanged, for the Skills after it.", "schema": { "type": "string", "maxLength": 86, "description": "The nextCursor of the page before, passed back unchanged, for the Skills after it." } } ], "responses": { "200": { "description": "A page of Skills.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The Skill's id." }, "handle": { "type": "string", "description": "The Skill's handle: its address in every route, fixed when it is created." }, "name": { "type": "string", "description": "The display name." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published` while a version is the one agents load; `draft` when none is." }, "activeVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The version agents load, or null when no version is live." }, "createdBy": { "anyOf": [ { "type": "string", "description": "Who created it: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed (ISO 8601)." }, "newestVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The newest version's number, live or not: the version a PUT of the same document answers with." } }, "required": [ "id", "handle", "name", "status", "activeVersion", "createdBy", "createdAt", "updatedAt", "newestVersion" ] }, "description": "This page of Skills, in byte order of the handle." }, "nextCursor": { "anyOf": [ { "type": "string", "description": "Pass back as `cursor` for the Skills after this page; null on the last page. Never build one." }, { "type": "null" } ] }, "limitClamped": { "description": "Present only when `limit` was more than 200.", "type": "object", "properties": { "requested": { "type": "number", "description": "The `limit` asked for." }, "applied": { "type": "number", "description": "The page size read instead." } }, "required": [ "requested", "applied" ] } }, "required": [ "skills", "nextCursor" ] } } } }, "400": { "description": "`validation_error`: `limit` is not a whole number from 1, `cursor` is not one this API gave, or the query carries a parameter this route does not define (named in the message).", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "validation_error" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "401": { "description": "`unauthorized`: No org API key was sent. Send one in the `x-api-key` header.\n\n`invalid_api_key`: The key is unknown, revoked or expired. The three are not told apart.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "unauthorized", "invalid_api_key" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "403": { "description": "`org_suspended`: The Org is suspended, so its keys do not work until it is restored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "org_suspended" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "404": { "description": "`not_found`: There is no such Skill or version (`context` names what was asked for); or, with the same answer so that nothing about another Org can be learned, the Org or Environment in the path is not the key's own, or the key holds no Skills scope; or Skills are not available on this Mindset instance, answered as a route that does not exist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "not_found" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } } } } }, "/api/v1/orgs/{orgSlug}/envs/{envSlug}/skills/{handle}": { "put": { "operationId": "putSkill", "summary": "Make the Skill at this handle equal this document", "description": "Declarative: send the whole Skill as it should be. If there is no Skill at the handle, it is created at version 1. If there is, and the document differs from its newest version, one version is added; if it is the same, nothing is added, so a retried call changes nothing. A different `name` renames the Skill and adds no version.\n\n`live` is required on every call. `true` makes the pushed version (or the identical newest one) the one agents load, in the same step, taking the previous one out of service: a Skill never has more than one live version. `false` stores it and leaves what is live as it was.\n\nThe Skill is at most 4194304 bytes as stored, instructions and files together, and the request body at most 16777216 bytes, so a Skill at its limit still fits once escaped as JSON. A Skill with problems is refused naming every one, and nothing is stored. Writes to one Skill are taken one at a time, whichever way they are made. Every change is recorded in the Org's audit trail, naming the key.\n\nNeeds a key holding `skills:write`.", "tags": [ "Skills" ], "x-required-scope": "skills:write", "parameters": [ { "name": "orgSlug", "in": "path", "required": true, "description": "The Org's slug: the key's own Org.", "schema": { "type": "string", "minLength": 1 } }, { "name": "envSlug", "in": "path", "required": true, "description": "The Environment's slug: the one the key was issued into.", "schema": { "type": "string", "minLength": 1 } }, { "name": "handle", "in": "path", "required": true, "description": "The Skill's handle.", "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "`*` only: create the Skill, and refuse (412) if a Skill already holds this handle.", "schema": { "type": "string", "enum": [ "*" ] } }, { "name": "If-Match", "in": "header", "required": false, "description": "One version, as the ETag a read or put of this Skill answered with (`\"3\"`; the bare number is accepted too): store the push only while that is still the Skill's newest version, and refuse (412) otherwise.", "schema": { "type": "string", "pattern": "^(?:\"[1-9][0-9]{0,9}\"|[1-9][0-9]{0,9})$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "x-counted-in": "code points" }, "description": { "type": "string", "maxLength": 1024, "x-counted-in": "code points" }, "instructions": { "type": "string" }, "files": { "type": "object", "propertyNames": { "type": "string", "maxLength": 512, "x-limit": "at most 512 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two" }, "additionalProperties": { "type": "string" }, "maxProperties": 10000 }, "license": { "type": "string", "minLength": 1, "maxLength": 500, "x-limit": "at most 500 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two" }, "compatibility": { "type": "string", "minLength": 1, "maxLength": 500, "x-counted-in": "code points" }, "metadata": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64, "x-limit": "at most 64 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two" }, "additionalProperties": { "type": "string", "maxLength": 500, "x-limit": "at most 500 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two" }, "maxProperties": 50 }, "allowedTools": { "type": "string", "minLength": 1, "maxLength": 2000, "x-limit": "at most 2000 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two" }, "live": { "type": "boolean", "description": "Required. Whether the pushed version becomes the one agents load: true makes it the active version, false stores it and leaves the active version unchanged." } }, "required": [ "name", "description", "instructions", "live" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "The Skill was updated (one version added) or was already this document (`outcome` says which).", "headers": { "ETag": { "description": "The Skill's newest version, quoted (`\"3\"`): what `If-Match` takes back.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "created", "updated", "unchanged" ], "description": "`created`: there was no Skill at this handle, and now there is, at version 1. `updated`: the document differed from the newest version, so one version was added. `unchanged`: the document is the newest version already, so nothing was added." }, "skill": { "type": "object", "properties": { "id": { "type": "string", "description": "The Skill's id." }, "handle": { "type": "string", "description": "The Skill's handle: its address in every route, fixed when it is created." }, "name": { "type": "string", "description": "The display name." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published` while a version is the one agents load; `draft` when none is." }, "activeVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The version agents load, or null when no version is live." }, "createdBy": { "anyOf": [ { "type": "string", "description": "Who created it: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed (ISO 8601)." } }, "required": [ "id", "handle", "name", "status", "activeVersion", "createdBy", "createdAt", "updatedAt" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The version the pushed document is: the new one, or the identical newest one." }, "live": { "type": "boolean", "description": "Whether that version is the one agents load after this call." }, "warnings": { "type": "array", "items": { "type": "string", "description": "A piece of advice." }, "description": "Advice the content earned. The call still succeeded." } }, "required": [ "outcome", "skill", "version", "live", "warnings" ] } } } }, "201": { "description": "There was no Skill at this handle; now there is, at version 1.", "headers": { "ETag": { "description": "The Skill's newest version, quoted (`\"3\"`): what `If-Match` takes back.", "schema": { "type": "string" } }, "Location": { "description": "The Skill's address: this same path.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "created", "updated", "unchanged" ], "description": "`created`: there was no Skill at this handle, and now there is, at version 1. `updated`: the document differed from the newest version, so one version was added. `unchanged`: the document is the newest version already, so nothing was added." }, "skill": { "type": "object", "properties": { "id": { "type": "string", "description": "The Skill's id." }, "handle": { "type": "string", "description": "The Skill's handle: its address in every route, fixed when it is created." }, "name": { "type": "string", "description": "The display name." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published` while a version is the one agents load; `draft` when none is." }, "activeVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The version agents load, or null when no version is live." }, "createdBy": { "anyOf": [ { "type": "string", "description": "Who created it: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed (ISO 8601)." } }, "required": [ "id", "handle", "name", "status", "activeVersion", "createdBy", "createdAt", "updatedAt" ] }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The version the pushed document is: the new one, or the identical newest one." }, "live": { "type": "boolean", "description": "Whether that version is the one agents load after this call." }, "warnings": { "type": "array", "items": { "type": "string", "description": "A piece of advice." }, "description": "Advice the content earned. The call still succeeded." } }, "required": [ "outcome", "skill", "version", "live", "warnings" ] } } } }, "400": { "description": "`validation_error`: The body is not JSON, not one object, misses a field, carries a field this API does not define (named in the message), or the Skill breaks a rule, including going live when that would give an agent more live Skills than it may hold (`reason` is `live_skill_cap`). Also a malformed `If-Match` or `If-None-Match` (`reason` is `precondition_header_invalid`).\n\n`invalid_handle`: The handle in the path is not one a Skill can have: 1 to 64 lowercase letters, digits and hyphens, not starting or ending with a hyphen, with no two hyphens in a row.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "validation_error", "invalid_handle" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "401": { "description": "`unauthorized`: No org API key was sent. Send one in the `x-api-key` header.\n\n`invalid_api_key`: The key is unknown, revoked or expired. The three are not told apart.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "unauthorized", "invalid_api_key" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "403": { "description": "`org_suspended`: The Org is suspended, so its keys do not work until it is restored.\n\n`unauthorized`: The key may read Skills but not write them: it needs `skills:write`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "org_suspended", "unauthorized" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "404": { "description": "`not_found`: There is no such Skill or version (`context` names what was asked for); or, with the same answer so that nothing about another Org can be learned, the Org or Environment in the path is not the key's own, or the key holds no Skills scope; or Skills are not available on this Mindset instance, answered as a route that does not exist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "not_found" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "409": { "description": "`version_conflict`: Another change to this Skill, made at the same moment through another way of changing Skills, got there first. Nothing was stored: read the Skill again and decide.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "version_conflict" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "412": { "description": "`precondition_failed`: A condition in `If-None-Match` or `If-Match` did not hold, so nothing was stored. `context.condition` says which, and `context.newestVersion` gives the Skill's newest version (null when there is no Skill).", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "precondition_failed" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "413": { "description": "`payload_too_large`: The request body is over 16777216 bytes, so it was refused before anything else was checked. `context.limitBytes` gives the limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "payload_too_large" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } } } }, "delete": { "operationId": "deleteSkill", "summary": "Delete a Skill", "description": "Deletes the Skill at this handle, with every version: no agent loads it from then on, and it is no longer listed. The handle is free again, so a later PUT to it creates a new Skill at version 1.\n\nWhen agents hold the Skill in their live configuration, the first call deletes nothing and is refused (409 `has_dependents`), naming them and giving a `fingerprint` for that list. Repeating the call with `confirmDependents` set to that fingerprint deletes it, provided the agents holding it are still the same; if they changed, it is refused again (409 `dependents_changed`) with the current list. A Skill no agent holds is deleted on the first call.\n\nWith `If-Match`, the Skill is deleted only while its newest version is the one named, and a 412 says when it has moved on: a caller that decided to delete what it read deletes nothing newer.\n\nDeleting is not undone through this API. A delete of a handle where there is no Skill, including a retried delete that already succeeded, answers 404. Every delete is recorded in the Org's audit trail, naming the key.\n\nNeeds a key holding `skills:write`.", "tags": [ "Skills" ], "x-required-scope": "skills:write", "parameters": [ { "name": "orgSlug", "in": "path", "required": true, "description": "The Org's slug: the key's own Org.", "schema": { "type": "string", "minLength": 1 } }, { "name": "envSlug", "in": "path", "required": true, "description": "The Environment's slug: the one the key was issued into.", "schema": { "type": "string", "minLength": 1 } }, { "name": "handle", "in": "path", "required": true, "description": "The Skill's handle.", "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } }, { "name": "If-Match", "in": "header", "required": false, "description": "One version, as the ETag a read or put of this Skill answered with (`\"3\"`; the bare number is accepted too): delete only while that is still the Skill's newest version, and refuse (412) otherwise.", "schema": { "type": "string", "pattern": "^(?:\"[1-9][0-9]{0,9}\"|[1-9][0-9]{0,9})$" } }, { "name": "confirmDependents", "in": "query", "required": false, "description": "The `fingerprint` a `has_dependents` or `dependents_changed` refusal gave, passed back unchanged once the person has seen which agents hold the Skill. Needed only when agents hold it.", "schema": { "type": "string", "maxLength": 64, "description": "The `fingerprint` a `has_dependents` or `dependents_changed` refusal gave, passed back unchanged once the person has seen which agents hold the Skill. Needed only when agents hold it." } } ], "responses": { "200": { "description": "The Skill was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true, "description": "Always true: the Skill is gone." }, "skill": { "type": "object", "properties": { "id": { "type": "string", "description": "The Skill's id." }, "handle": { "type": "string", "description": "The Skill's handle: its address in every route, fixed when it is created." }, "name": { "type": "string", "description": "The display name." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published` while a version is the one agents load; `draft` when none is." }, "activeVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The version agents load, or null when no version is live." }, "createdBy": { "anyOf": [ { "type": "string", "description": "Who created it: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed (ISO 8601)." } }, "required": [ "id", "handle", "name", "status", "activeVersion", "createdBy", "createdAt", "updatedAt" ], "description": "The Skill as it was. Its handle is free: a PUT to it now creates a new Skill at version 1." } }, "required": [ "deleted", "skill" ] } } } }, "400": { "description": "`validation_error`: `confirmDependents` is longer than any fingerprint, the query carries a parameter this route does not define (named in the message), `If-Match` does not name one version, or `If-None-Match` was sent (`reason` is `precondition_header_invalid` for the two headers).", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "validation_error" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "401": { "description": "`unauthorized`: No org API key was sent. Send one in the `x-api-key` header.\n\n`invalid_api_key`: The key is unknown, revoked or expired. The three are not told apart.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "unauthorized", "invalid_api_key" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "403": { "description": "`org_suspended`: The Org is suspended, so its keys do not work until it is restored.\n\n`unauthorized`: The key may read Skills but not delete them: it needs `skills:write`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "org_suspended", "unauthorized" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "404": { "description": "`not_found`: There is no such Skill or version (`context` names what was asked for); or, with the same answer so that nothing about another Org can be learned, the Org or Environment in the path is not the key's own, or the key holds no Skills scope; or Skills are not available on this Mindset instance, answered as a route that does not exist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "not_found" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "409": { "description": "`has_dependents`: Agents hold the Skill in their live configuration, so it was not deleted: deleting it takes it away from each of them. `context.dependents` names them (at most 200; `context.truncated` says when there are more) and `context.fingerprint` stands for that list. To delete anyway, repeat the call with `confirmDependents` set to the fingerprint.\n\n`dependents_changed`: The `confirmDependents` sent is not the fingerprint of the agents holding the Skill now: which agents hold it changed since that fingerprint was given, so it was not deleted. `context` carries the current list and its fingerprint, as `has_dependents` does.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "has_dependents", "dependents_changed" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "412": { "description": "`precondition_failed`: `If-Match` named a version that is no longer the Skill's newest, so nothing was deleted. `context.newestVersion` gives the newest.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "precondition_failed" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } } } }, "get": { "operationId": "getSkill", "summary": "Read a Skill as it stands", "description": "The Skill, its newest version's record, and everything that version holds, in the shape a PUT takes. The ETag is that version, for `If-Match`. Which version agents load is `skill.activeVersion`. Every route names the Skill by its handle.\n\nNeeds a key holding `skills:read`.", "tags": [ "Skills" ], "x-required-scope": "skills:read", "parameters": [ { "name": "orgSlug", "in": "path", "required": true, "description": "The Org's slug: the key's own Org.", "schema": { "type": "string", "minLength": 1 } }, { "name": "envSlug", "in": "path", "required": true, "description": "The Environment's slug: the one the key was issued into.", "schema": { "type": "string", "minLength": 1 } }, { "name": "handle", "in": "path", "required": true, "description": "The Skill's handle.", "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } } ], "responses": { "200": { "description": "The Skill and its newest version.", "headers": { "ETag": { "description": "The Skill's newest version, quoted (`\"3\"`): what `If-Match` takes back.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "id": { "type": "string", "description": "The Skill's id." }, "handle": { "type": "string", "description": "The Skill's handle: its address in every route, fixed when it is created." }, "name": { "type": "string", "description": "The display name." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published` while a version is the one agents load; `draft` when none is." }, "activeVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The version agents load, or null when no version is live." }, "createdBy": { "anyOf": [ { "type": "string", "description": "Who created it: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed (ISO 8601)." } }, "required": [ "id", "handle", "name", "status", "activeVersion", "createdBy", "createdAt", "updatedAt" ] }, "version": { "type": "object", "properties": { "id": { "type": "string", "description": "The version's id." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The version's number. The first is 1, and each new version is one more." }, "description": { "type": "string", "description": "The description this version holds." }, "author": { "anyOf": [ { "type": "string", "description": "Who wrote this version: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "approvedBy": { "anyOf": [ { "type": "string", "description": "Who last made this version live, the same way; null when it never was." }, { "type": "null" } ] }, "authorLabel": { "type": "string", "description": "Who wrote it, as a person reads it: a member's name, or `API key`." }, "approvedByLabel": { "anyOf": [ { "type": "string", "description": "Who last made it live, the same way; null when it never was." }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was last made live (ISO 8601); null when it never was." }, { "type": "null" } ] }, "isActive": { "type": "boolean", "description": "Whether this is the version agents load. At most one version of a Skill is." }, "parentVersionId": { "anyOf": [ { "type": "string", "description": "The version this one was made from, or null for the first." }, { "type": "null" } ] }, "totalBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The instructions and every file together, in bytes as stored: at most 4194304." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." } }, "required": [ "id", "version", "description", "author", "approvedBy", "authorLabel", "approvedByLabel", "approvedAt", "isActive", "parentVersionId", "totalBytes", "createdAt" ] }, "document": { "type": "object", "properties": { "name": { "type": "string", "description": "The Skill's display name as it is now: a name is not versioned, so reading an older version gives the current one." }, "description": { "type": "string", "description": "When the Skill applies: what an agent reads to decide whether to load it." }, "instructions": { "type": "string", "description": "The Skill's instructions: the body of its SKILL.md." }, "files": { "type": "object", "propertyNames": { "type": "string", "description": "A path relative to the Skill's root." }, "additionalProperties": { "type": "string", "description": "The file's text." }, "maxProperties": 10000, "description": "The Skill's other files, by path relative to its root, each with its text." }, "license": { "type": "string", "description": "The Skill's license, as written." }, "compatibility": { "type": "string", "description": "What the Skill needs to run, as written." }, "metadata": { "type": "object", "propertyNames": { "type": "string", "description": "A key." }, "additionalProperties": { "type": "string", "description": "Its value." }, "maxProperties": 50, "description": "Further frontmatter, as written." }, "allowedTools": { "type": "string", "description": "The tools the Skill names as allowed, as written. It has no effect in Mindset." } }, "required": [ "name", "description", "instructions", "files" ], "description": "Everything the version holds, in the shape a PUT takes: read it, change it, and push it back." } }, "required": [ "skill", "version", "document" ] } } } }, "401": { "description": "`unauthorized`: No org API key was sent. Send one in the `x-api-key` header.\n\n`invalid_api_key`: The key is unknown, revoked or expired. The three are not told apart.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "unauthorized", "invalid_api_key" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "403": { "description": "`org_suspended`: The Org is suspended, so its keys do not work until it is restored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "org_suspended" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "404": { "description": "`not_found`: There is no such Skill or version (`context` names what was asked for); or, with the same answer so that nothing about another Org can be learned, the Org or Environment in the path is not the key's own, or the key holds no Skills scope; or Skills are not available on this Mindset instance, answered as a route that does not exist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "not_found" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } } } } }, "/api/v1/orgs/{orgSlug}/envs/{envSlug}/skills/{handle}/versions": { "get": { "operationId": "listSkillVersions", "summary": "List a Skill's versions", "description": "Its versions, newest first, each naming who wrote it and when, and who last made it live. 50 per page unless `limit` says otherwise, at most 200; `nextCursor` continues it.\n\nNeeds a key holding `skills:read`.", "tags": [ "Skills" ], "x-required-scope": "skills:read", "parameters": [ { "name": "orgSlug", "in": "path", "required": true, "description": "The Org's slug: the key's own Org.", "schema": { "type": "string", "minLength": 1 } }, { "name": "envSlug", "in": "path", "required": true, "description": "The Environment's slug: the one the key was issued into.", "schema": { "type": "string", "minLength": 1 } }, { "name": "handle", "in": "path", "required": true, "description": "The Skill's handle.", "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } }, { "name": "limit", "in": "query", "required": false, "description": "Versions per page. Default 50; a larger number reads 200, and the answer's limitClamped says so.", "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Versions per page. Default 50; a larger number reads 200, and the answer's limitClamped says so." } }, { "name": "cursor", "in": "query", "required": false, "description": "The nextCursor of the page before, passed back unchanged, for the versions older than it.", "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$", "description": "The nextCursor of the page before, passed back unchanged, for the versions older than it." } } ], "responses": { "200": { "description": "A page of versions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The version's id." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The version's number. The first is 1, and each new version is one more." }, "description": { "type": "string", "description": "The description this version holds." }, "author": { "anyOf": [ { "type": "string", "description": "Who wrote this version: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "approvedBy": { "anyOf": [ { "type": "string", "description": "Who last made this version live, the same way; null when it never was." }, { "type": "null" } ] }, "authorLabel": { "type": "string", "description": "Who wrote it, as a person reads it: a member's name, or `API key`." }, "approvedByLabel": { "anyOf": [ { "type": "string", "description": "Who last made it live, the same way; null when it never was." }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was last made live (ISO 8601); null when it never was." }, { "type": "null" } ] }, "isActive": { "type": "boolean", "description": "Whether this is the version agents load. At most one version of a Skill is." }, "parentVersionId": { "anyOf": [ { "type": "string", "description": "The version this one was made from, or null for the first." }, { "type": "null" } ] }, "totalBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The instructions and every file together, in bytes as stored: at most 4194304." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." } }, "required": [ "id", "version", "description", "author", "approvedBy", "authorLabel", "approvedByLabel", "approvedAt", "isActive", "parentVersionId", "totalBytes", "createdAt" ] }, "description": "This page of versions, newest first." }, "nextCursor": { "anyOf": [ { "type": "string", "description": "Pass back as `cursor` for the versions older than this page; null on the last page. Never build one." }, { "type": "null" } ] }, "limitClamped": { "description": "Present only when `limit` was more than 200.", "type": "object", "properties": { "requested": { "type": "number", "description": "The `limit` asked for." }, "applied": { "type": "number", "description": "The page size read instead." } }, "required": [ "requested", "applied" ] } }, "required": [ "versions", "nextCursor" ] } } } }, "400": { "description": "`validation_error`: `limit` is not a whole number from 1, `cursor` is not one this API gave, or the query carries a parameter this route does not define (named in the message).", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "validation_error" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "401": { "description": "`unauthorized`: No org API key was sent. Send one in the `x-api-key` header.\n\n`invalid_api_key`: The key is unknown, revoked or expired. The three are not told apart.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "unauthorized", "invalid_api_key" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "403": { "description": "`org_suspended`: The Org is suspended, so its keys do not work until it is restored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "org_suspended" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "404": { "description": "`not_found`: There is no such Skill or version (`context` names what was asked for); or, with the same answer so that nothing about another Org can be learned, the Org or Environment in the path is not the key's own, or the key holds no Skills scope; or Skills are not available on this Mindset instance, answered as a route that does not exist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "not_found" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } } } } }, "/api/v1/orgs/{orgSlug}/envs/{envSlug}/skills/{handle}/versions/{version}": { "get": { "operationId": "getSkillVersion", "summary": "Read one version of a Skill", "description": "The Skill, the version's record, and everything the version holds, in the shape a PUT takes.\n\nNeeds a key holding `skills:read`.", "tags": [ "Skills" ], "x-required-scope": "skills:read", "parameters": [ { "name": "orgSlug", "in": "path", "required": true, "description": "The Org's slug: the key's own Org.", "schema": { "type": "string", "minLength": 1 } }, { "name": "envSlug", "in": "path", "required": true, "description": "The Environment's slug: the one the key was issued into.", "schema": { "type": "string", "minLength": 1 } }, { "name": "handle", "in": "path", "required": true, "description": "The Skill's handle.", "schema": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" } }, { "name": "version", "in": "path", "required": true, "description": "A version's number.", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } } ], "responses": { "200": { "description": "The Skill and the version.", "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "object", "properties": { "id": { "type": "string", "description": "The Skill's id." }, "handle": { "type": "string", "description": "The Skill's handle: its address in every route, fixed when it is created." }, "name": { "type": "string", "description": "The display name." }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "`published` while a version is the one agents load; `draft` when none is." }, "activeVersion": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The version agents load, or null when no version is live." }, "createdBy": { "anyOf": [ { "type": "string", "description": "Who created it: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it last changed (ISO 8601)." } }, "required": [ "id", "handle", "name", "status", "activeVersion", "createdBy", "createdAt", "updatedAt" ] }, "version": { "type": "object", "properties": { "id": { "type": "string", "description": "The version's id." }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "The version's number. The first is 1, and each new version is one more." }, "description": { "type": "string", "description": "The description this version holds." }, "author": { "anyOf": [ { "type": "string", "description": "Who wrote this version: a member's id, or `key:` and the id of the org API key that did." }, { "type": "null" } ] }, "approvedBy": { "anyOf": [ { "type": "string", "description": "Who last made this version live, the same way; null when it never was." }, { "type": "null" } ] }, "authorLabel": { "type": "string", "description": "Who wrote it, as a person reads it: a member's name, or `API key`." }, "approvedByLabel": { "anyOf": [ { "type": "string", "description": "Who last made it live, the same way; null when it never was." }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was last made live (ISO 8601); null when it never was." }, { "type": "null" } ] }, "isActive": { "type": "boolean", "description": "Whether this is the version agents load. At most one version of a Skill is." }, "parentVersionId": { "anyOf": [ { "type": "string", "description": "The version this one was made from, or null for the first." }, { "type": "null" } ] }, "totalBytes": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The instructions and every file together, in bytes as stored: at most 4194304." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "description": "When it was created (ISO 8601)." } }, "required": [ "id", "version", "description", "author", "approvedBy", "authorLabel", "approvedByLabel", "approvedAt", "isActive", "parentVersionId", "totalBytes", "createdAt" ] }, "document": { "type": "object", "properties": { "name": { "type": "string", "description": "The Skill's display name as it is now: a name is not versioned, so reading an older version gives the current one." }, "description": { "type": "string", "description": "When the Skill applies: what an agent reads to decide whether to load it." }, "instructions": { "type": "string", "description": "The Skill's instructions: the body of its SKILL.md." }, "files": { "type": "object", "propertyNames": { "type": "string", "description": "A path relative to the Skill's root." }, "additionalProperties": { "type": "string", "description": "The file's text." }, "maxProperties": 10000, "description": "The Skill's other files, by path relative to its root, each with its text." }, "license": { "type": "string", "description": "The Skill's license, as written." }, "compatibility": { "type": "string", "description": "What the Skill needs to run, as written." }, "metadata": { "type": "object", "propertyNames": { "type": "string", "description": "A key." }, "additionalProperties": { "type": "string", "description": "Its value." }, "maxProperties": 50, "description": "Further frontmatter, as written." }, "allowedTools": { "type": "string", "description": "The tools the Skill names as allowed, as written. It has no effect in Mindset." } }, "required": [ "name", "description", "instructions", "files" ], "description": "Everything the version holds, in the shape a PUT takes: read it, change it, and push it back." } }, "required": [ "skill", "version", "document" ] } } } }, "400": { "description": "`validation_error`: The version in the path is not a whole number from 1.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "validation_error" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "401": { "description": "`unauthorized`: No org API key was sent. Send one in the `x-api-key` header.\n\n`invalid_api_key`: The key is unknown, revoked or expired. The three are not told apart.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "unauthorized", "invalid_api_key" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "403": { "description": "`org_suspended`: The Org is suspended, so its keys do not work until it is restored.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "org_suspended" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } }, "404": { "description": "`not_found`: There is no such Skill or version (`context` names what was asked for); or, with the same answer so that nothing about another Org can be learned, the Org or Environment in the path is not the key's own, or the key holds no Skills scope; or Skills are not available on this Mindset instance, answered as a route that does not exist.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "Branch on this. These are the codes this answer gives today; treat one you do not know by the HTTP status.", "examples": [ "not_found" ] }, "message": { "type": "string", "description": "A sentence for a person. Do not parse it: branch on `code`." }, "context": { "type": "object", "description": "Machine-readable detail, when the refusal has any.", "additionalProperties": true } } } } } } } } } }, "components": { "securitySchemes": { "orgApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "An org API key (`msk_…`), issued by an Org admin in the console." } } } }