{
  "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: each tag below says what its routes are for. Today that includes creating the agent session one of your users talks to an embedded agent in.\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 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**Requests may be refused with 429.** Each Mindset instance limits the work it takes at once, to keep serving everyone: how many requests one key has in progress and sends per minute, each Org's share of an instance, and how much request body an instance holds at once. A request over a limit is refused with 429 `rate_limited` and a `Retry-After` header, before any of its body is processed. Wait that many seconds and send it again; a caller that retries at once is refused again. When your organisation's share of an instance, or the instance itself, is full (your own burst of large requests can fill your share), a client still sending a body when it is refused may see the connection close before it reads the 429: treat that like a 429, wait a moment and send it again. A refused request that carries no credential (an inbound webhook, an OAuth request) and is still sending a body is always answered that way. As a rough guide, which this API does not promise, limiting may start at around 8 Skill writes in progress per key, fewer when each is large, and around 300 a minute; reads and agent session starts sit higher. Each limit is counted per instance and a deployment may set its own values, so a well-behaved caller sends a few requests at a time and honours `Retry-After` rather than aiming at a number.\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": "Keep an Environment's Skills in step with the ones your system holds: list them, push each one, read it back, choose which of its versions is active, enable or disable it, and delete the ones your system no longer has. Every call to a Skills route is counted against the key that made it, per route, version of the API and day.\n\nA Skill is 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 active. A Skill is used only while it is enabled AND a version is active: agents then load the active version. A new Skill starts disabled, and activating a version never enables it. A Skill reaches an agent's conversations once it is attached to that agent, which this API does not attach: an Org admin's own AI tool attaches it through the admin MCP, once per agent, which saves an agent version that is not active, and the Skill reaches the agent once a person has activated that agent version in the web UI. From then on, while the Skill is enabled, the version activated here is the one that agent loads, from its next turn. A single embedded session can also be given a Skill with no attach at all: its create request names the Skill under `additionalResources.skills` (see `createAgentSession` in this document)."
    },
    {
      "name": "Agent sessions",
      "description": "The session an embedded agent runs in, for one of your users. Your backend creates it with an org API key that has Full access, and hands the browser only the credential it answers with: never the key. The Agent SDK runs the conversation with that credential, and renews it itself."
    }
  ],
  "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, its active version, whether it is enabled, 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."
                          },
                          "activeVersion": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "exclusiveMinimum": 0,
                                "maximum": 9007199254740991
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                          },
                          "enabled": {
                            "type": "boolean",
                            "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                          },
                          "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, active or not: the version a PUT of the same document answers with."
                          }
                        },
                        "required": [
                          "id",
                          "handle",
                          "name",
                          "activeVersion",
                          "enabled",
                          "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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` is a change like any other: it adds a version carrying the new name, and agents see the new name once that version is active.\n\n`activate` is required on every call. `true` activates the pushed version (or the identical newest one) in the same step: it becomes the Skill's active version, and the version active before stops being active, since a Skill never has more than one active version. `false` stores it and leaves the active version as it was.\n\n`activate` never enables or disables the Skill. A new Skill starts disabled, whatever `activate` says, and agents use it only once it is enabled (`enableSkill`): a Skill is used only while it is enabled AND a version is active. An enabled Skill stays enabled, so on it `activate: true` puts the pushed version in front of every agent that holds the Skill, from its next turn.\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"
                  },
                  "activate": {
                    "type": "boolean",
                    "description": "Required. true activates the pushed version: it becomes the Skill's active version. false stores it and leaves the active version as it was. It never enables or disables the Skill: a new Skill starts disabled whatever this says, and agents load the active version only while the Skill is enabled."
                  }
                },
                "required": [
                  "name",
                  "description",
                  "instructions",
                  "activate"
                ],
                "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."
                        },
                        "activeVersion": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "exclusiveMinimum": 0,
                              "maximum": 9007199254740991
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                        },
                        "enabled": {
                          "type": "boolean",
                          "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                        },
                        "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",
                        "activeVersion",
                        "enabled",
                        "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."
                    },
                    "active": {
                      "type": "boolean",
                      "description": "Whether that version is the Skill's active version after this call. Agents load it only while the Skill is also enabled (`skill.enabled`), which a PUT never changes."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A piece of advice."
                      },
                      "description": "Advice the content earned. The call still succeeded."
                    }
                  },
                  "required": [
                    "outcome",
                    "skill",
                    "version",
                    "active",
                    "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."
                        },
                        "activeVersion": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "exclusiveMinimum": 0,
                              "maximum": 9007199254740991
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                        },
                        "enabled": {
                          "type": "boolean",
                          "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                        },
                        "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",
                        "activeVersion",
                        "enabled",
                        "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."
                    },
                    "active": {
                      "type": "boolean",
                      "description": "Whether that version is the Skill's active version after this call. Agents load it only while the Skill is also enabled (`skill.enabled`), which a PUT never changes."
                    },
                    "warnings": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A piece of advice."
                      },
                      "description": "Advice the content earned. The call still succeeded."
                    }
                  },
                  "required": [
                    "outcome",
                    "skill",
                    "version",
                    "active",
                    "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 activating a version of an enabled Skill with none active when that would give an agent more Skills in use 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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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' active versions hold the Skill, 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 it matches the agents that hold the Skill now; one that does not match (the list moved, or the value was mistyped) is refused (409 `dependents_changed`) with the current list and its fingerprint. 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."
                        },
                        "activeVersion": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "exclusiveMinimum": 0,
                              "maximum": 9007199254740991
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                        },
                        "enabled": {
                          "type": "boolean",
                          "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                        },
                        "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",
                        "activeVersion",
                        "enabled",
                        "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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' active versions hold the Skill, 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 does not match the agents that hold the Skill now, so it was not deleted. The code is checked only against the current holders: a mistyped code and one given before the list moved read the same. `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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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`. The active version is `skill.activeVersion`, and agents load it only while `skill.enabled` is true. 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."
                        },
                        "activeVersion": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "exclusiveMinimum": 0,
                              "maximum": 9007199254740991
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                        },
                        "enabled": {
                          "type": "boolean",
                          "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                        },
                        "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",
                        "activeVersion",
                        "enabled",
                        "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."
                        },
                        "name": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "The display name this version carries. Agents are told the active version's name, so a rename is a new version. Null only for a version saved before versions carried a name."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "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"
                            }
                          ]
                        },
                        "activatedBy": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "Who first activated this version: a member's id, or `key:` and the id of the org API key that did; null when it never was. Activating it again later keeps this."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "authorLabel": {
                          "type": "string",
                          "description": "Who wrote it, as a person reads it: a member's name, or an org API key's name and prefix as Settings shows them (API key 'Skills sync' (msk_…)), followed by (revoked) once the key is revoked."
                        },
                        "activatedByLabel": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "Who first activated it, as a person reads it, the same way as `authorLabel`; null when it never was."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "activatedAt": {
                          "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 first activated (ISO 8601); null when it never was. Activating it again later keeps this."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "isActive": {
                          "type": "boolean",
                          "description": "Whether this is the Skill's active version, the one agents load while the Skill is enabled. At most one version of a Skill is."
                        },
                        "parentVersionId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "The version this one was built on: the version named as its base when it was saved, else the Skill's newest version then, whatever was active. Null for the first version, and for a version saved, before this rule applied, while no version was active."
                            },
                            {
                              "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",
                        "name",
                        "description",
                        "author",
                        "activatedBy",
                        "authorLabel",
                        "activatedByLabel",
                        "activatedAt",
                        "isActive",
                        "parentVersionId",
                        "totalBytes",
                        "createdAt"
                      ]
                    },
                    "document": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "The display name this version carries: a rename is a new version, so reading an older version gives the name it had."
                        },
                        "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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 first activated it. 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."
                          },
                          "name": {
                            "anyOf": [
                              {
                                "type": "string",
                                "description": "The display name this version carries. Agents are told the active version's name, so a rename is a new version. Null only for a version saved before versions carried a name."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "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"
                              }
                            ]
                          },
                          "activatedBy": {
                            "anyOf": [
                              {
                                "type": "string",
                                "description": "Who first activated this version: a member's id, or `key:` and the id of the org API key that did; null when it never was. Activating it again later keeps this."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "authorLabel": {
                            "type": "string",
                            "description": "Who wrote it, as a person reads it: a member's name, or an org API key's name and prefix as Settings shows them (API key 'Skills sync' (msk_…)), followed by (revoked) once the key is revoked."
                          },
                          "activatedByLabel": {
                            "anyOf": [
                              {
                                "type": "string",
                                "description": "Who first activated it, as a person reads it, the same way as `authorLabel`; null when it never was."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "activatedAt": {
                            "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 first activated (ISO 8601); null when it never was. Activating it again later keeps this."
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "isActive": {
                            "type": "boolean",
                            "description": "Whether this is the Skill's active version, the one agents load while the Skill is enabled. At most one version of a Skill is."
                          },
                          "parentVersionId": {
                            "anyOf": [
                              {
                                "type": "string",
                                "description": "The version this one was built on: the version named as its base when it was saved, else the Skill's newest version then, whatever was active. Null for the first version, and for a version saved, before this rule applied, while no version was active."
                              },
                              {
                                "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",
                          "name",
                          "description",
                          "author",
                          "activatedBy",
                          "authorLabel",
                          "activatedByLabel",
                          "activatedAt",
                          "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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."
                        },
                        "activeVersion": {
                          "anyOf": [
                            {
                              "type": "integer",
                              "exclusiveMinimum": 0,
                              "maximum": 9007199254740991
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                        },
                        "enabled": {
                          "type": "boolean",
                          "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                        },
                        "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",
                        "activeVersion",
                        "enabled",
                        "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."
                        },
                        "name": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "The display name this version carries. Agents are told the active version's name, so a rename is a new version. Null only for a version saved before versions carried a name."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "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"
                            }
                          ]
                        },
                        "activatedBy": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "Who first activated this version: a member's id, or `key:` and the id of the org API key that did; null when it never was. Activating it again later keeps this."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "authorLabel": {
                          "type": "string",
                          "description": "Who wrote it, as a person reads it: a member's name, or an org API key's name and prefix as Settings shows them (API key 'Skills sync' (msk_…)), followed by (revoked) once the key is revoked."
                        },
                        "activatedByLabel": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "Who first activated it, as a person reads it, the same way as `authorLabel`; null when it never was."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "activatedAt": {
                          "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 first activated (ISO 8601); null when it never was. Activating it again later keeps this."
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "isActive": {
                          "type": "boolean",
                          "description": "Whether this is the Skill's active version, the one agents load while the Skill is enabled. At most one version of a Skill is."
                        },
                        "parentVersionId": {
                          "anyOf": [
                            {
                              "type": "string",
                              "description": "The version this one was built on: the version named as its base when it was saved, else the Skill's newest version then, whatever was active. Null for the first version, and for a version saved, before this rule applied, while no version was active."
                            },
                            {
                              "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",
                        "name",
                        "description",
                        "author",
                        "activatedBy",
                        "authorLabel",
                        "activatedByLabel",
                        "activatedAt",
                        "isActive",
                        "parentVersionId",
                        "totalBytes",
                        "createdAt"
                      ]
                    },
                    "document": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "The display name this version carries: a rename is a new version, so reading an older version gives the name it had."
                        },
                        "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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}/activate": {
      "post": {
        "operationId": "activateSkillVersion",
        "summary": "Activate one version of a Skill",
        "description": "Makes the version named in the path the Skill's active version, whichever it is: a version never active before, an earlier one, or the one already active (which changes nothing). The version active before stops being active: a Skill never has more than one active version. While the Skill is enabled, every agent that holds it loads the version activated here from its next turn.\n\nActivating never enables the Skill: a disabled Skill stays disabled, and no agent uses it until it is enabled (`enableSkill`).\n\nThis is how to bring back an earlier version: name its number. Nothing is copied and no version is added. `PUT` with `activate: true` stays the way to send new content and activate it in one step.\n\nEvery 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": "version",
            "in": "path",
            "required": true,
            "description": "A version's number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The Skill as it now stands: `activeVersion` is the version named.",
            "content": {
              "application/json": {
                "schema": {
                  "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."
                    },
                    "activeVersion": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                    },
                    "enabled": {
                      "type": "boolean",
                      "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                    },
                    "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",
                    "activeVersion",
                    "enabled",
                    "createdBy",
                    "createdAt",
                    "updatedAt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`validation_error`: The version in the path is not a whole number from 1, or the Skill is enabled with no version active and activating one would give an agent more Skills in use than it may hold (`reason` is `live_skill_cap`).",
            "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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}/enable": {
      "post": {
        "operationId": "enableSkill",
        "summary": "Enable a Skill",
        "description": "Enables the Skill: from the next turn of every agent that holds it, the agent is told of it and loads its active version. A Skill is used only while it is enabled AND a version is active, so enabling is refused while no version is active: activate one first (`activateSkillVersion`, or `PUT` with `activate: true`). A Skill already enabled answers the same, and stays as it is.\n\nSend `shownEnabled` to act only on the state your system last read: when the Skill is not in that state now, nothing is changed and the request is refused (409 `enabled_state_changed`). With no body, it is enabled whatever its state.\n\nEvery 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]+)*$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "shownEnabled": {
                    "description": "The Enabled state the caller acted on: true when it last read it enabled, false when it read it disabled. When the state now is not that one, nothing is changed and the act is refused. Leave it out to act whatever the state is.",
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Skill as it now stands: `enabled` is true.",
            "content": {
              "application/json": {
                "schema": {
                  "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."
                    },
                    "activeVersion": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                    },
                    "enabled": {
                      "type": "boolean",
                      "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                    },
                    "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",
                    "activeVersion",
                    "enabled",
                    "createdBy",
                    "createdAt",
                    "updatedAt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`validation_error`: The Skill has no active version (`reason` is `no_active_version`); enabling it would give an agent more Skills in use than it may hold (`reason` is `live_skill_cap`); or the body is not JSON, not one object, or carries a field other than `shownEnabled`.",
            "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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": "`enabled_state_changed`: The Skill is not in the Enabled state the request's `shownEnabled` said it was in, so nothing was changed. `context.enabled` gives the state now: read the Skill again and decide.\n\n`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": [
                        "enabled_state_changed",
                        "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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}/disable": {
      "post": {
        "operationId": "disableSkill",
        "summary": "Disable a Skill",
        "description": "Disables the Skill: from the next turn, no agent is told of it or loads it, though agents keep holding it, and no embedded session can add it. Its active version stays active, so enabling it again uses that same version; every version is kept. A Skill already disabled answers the same, and stays as it is.\n\nSend `shownEnabled` to act only on the state your system last read: when the Skill is not in that state now, nothing is changed and the request is refused (409 `enabled_state_changed`). With no body, it is disabled whatever its state.\n\nEvery 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]+)*$"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "shownEnabled": {
                    "description": "The Enabled state the caller acted on: true when it last read it enabled, false when it read it disabled. When the state now is not that one, nothing is changed and the act is refused. Leave it out to act whatever the state is.",
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The Skill as it now stands: `enabled` is false.",
            "content": {
              "application/json": {
                "schema": {
                  "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."
                    },
                    "activeVersion": {
                      "anyOf": [
                        {
                          "type": "integer",
                          "exclusiveMinimum": 0,
                          "maximum": 9007199254740991
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "The active version, or null when no version is active. Agents load it only while the Skill is enabled: the Skill is used only while it is enabled AND a version is active."
                    },
                    "enabled": {
                      "type": "boolean",
                      "description": "Whether the Skill is enabled. The Skill is used only while it is enabled AND a version is active: agents load its active version then, and never while it is disabled. A new Skill starts disabled, and activating a version leaves it as it is: `enableSkill` and `disableSkill` change it."
                    },
                    "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",
                    "activeVersion",
                    "enabled",
                    "createdBy",
                    "createdAt",
                    "updatedAt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`validation_error`: The body is not JSON, not one object, or carries a field other than `shownEnabled`.",
            "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`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": [
                        "credential_kind_not_accepted",
                        "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it.",
            "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": "`enabled_state_changed`: The Skill is not in the Enabled state the request's `shownEnabled` said it was in, so nothing was changed. `context.enabled` gives the state now: read the Skill again and decide.\n\n`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": [
                        "enabled_state_changed",
                        "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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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}/agent-sessions": {
      "post": {
        "operationId": "createAgentSession",
        "summary": "Create a session for one of your users to talk to one agent",
        "description": "Your backend calls this when one of its users opens a page that embeds an agent. It resolves the user in this Org by `user.email` or `user.externalId` (exactly one), creating them when `createUserIfNeeded` is true, and answers with a session credential scoped to that user and the one agent named in `agent`, by handle or id. Pass the whole answer to the Agent SDK in the browser: the key never leaves your server.\n\nThe agent must be one of this Org's own agents, enabled, with \"Embedded in your own product\" ticked and an active version. The session reaches exactly what that version grants. `additionalResources.skills` adds Skills of this Environment for this session only, each enabled with an active version and named by handle or id; nothing is ever removed. `attribution` is your own labels for the session, carried on every span of its runs.\n\nNeeds a key with Full access: a key limited to Skills cannot call it.",
        "tags": [
          "Agent sessions"
        ],
        "x-required-scope": "full",
        "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
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "user": {
                    "type": "object",
                    "properties": {
                      "email": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 320,
                        "pattern": "^\\s*[^\\s@]+@[^\\s@]+\\s*$",
                        "x-limit": "at most 320 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two"
                      },
                      "externalId": {
                        "type": "string",
                        "minLength": 1,
                        "pattern": "^\\s*[a-zA-Z0-9_-]{1,100}\\s*$"
                      }
                    },
                    "additionalProperties": false,
                    "oneOf": [
                      {
                        "properties": {
                          "email": true
                        },
                        "required": [
                          "email"
                        ]
                      },
                      {
                        "properties": {
                          "externalId": true
                        },
                        "required": [
                          "externalId"
                        ]
                      }
                    ]
                  },
                  "agent": {
                    "type": "string",
                    "minLength": 1
                  },
                  "createUserIfNeeded": {
                    "type": "boolean"
                  },
                  "attribution": {
                    "type": "object",
                    "propertyNames": {
                      "type": "string",
                      "minLength": 1,
                      "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": 256,
                      "x-limit": "at most 256 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two"
                    },
                    "maxProperties": 16
                  },
                  "additionalResources": {
                    "type": "object",
                    "properties": {
                      "skills": {
                        "maxItems": 20,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 65,
                          "x-limit": "at most 65 characters as JavaScript counts them: a character outside the Basic Multilingual Plane, such as most emoji, counts as two"
                        }
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "user",
                  "agent"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The session.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session": {
                      "type": "string",
                      "description": "The session credential. Hand the whole response to the Agent SDK in the browser, unmodified: what the string holds is the SDK's to read, not part of this contract, and may change."
                    },
                    "enabledFeatures": {
                      "description": "The release flags this Mindset instance has switched on that the embedded agent can act on. Pass it to the SDK with the session.",
                      "readOnly": true,
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "A release flag's name."
                      }
                    }
                  },
                  "required": [
                    "session"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "`validation_error`: The body is not JSON, misses a field, carries a field this API does not define, names both or neither of `user.email` and `user.externalId`, or breaks a limit; or a Skill in `additionalResources.skills` is not an enabled Skill of this Environment with an active version (each is named); or the agent has no active version to embed.",
            "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": "`credential_kind_not_accepted`: The credential sent is not an org API key: a platform key, sent here in any header, is refused before anything else is checked. `context.credential` names what was sent and `context.acceptedAt` where it is accepted.\n\n`org_suspended`: The Org is suspended, so its keys do not work until it is restored.\n\n`agent_not_available_here`: The agent cannot be embedded: a person ticks \"Embedded in your own product\" on its Versions & Availability tab. `context.surface` names the surface.",
            "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": [
                        "credential_kind_not_accepted",
                        "org_suspended",
                        "agent_not_available_here"
                      ]
                    },
                    "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`: The key may not make this request: it lacks the access or scope the operation needs, the path names an Environment the key was not issued into or one that does not exist, or an Org that is not the key's own, real or not. Every one of these gets the same answer, byte for byte (`message` is `no such org` and `context` is empty), so nothing about the key's Org, its Environments or its access can be learned from it. A refusal in the key's own Org is recorded in that Org's audit trail with its reason, where an admin of the Org can read it. For this operation, there is no agent with that handle or id in this Org, or the user is not in this Org and `createUserIfNeeded` was not true.",
            "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": "`user_not_active`: The user is a member of this Org but not active: invited and never onboarded, or removed. Re-admit them before creating a session for them.\n\n`no_version_in_force`: The agent has configuration versions but none is active, so a session would have nothing to run. A person activates a version on the agent's Versions page first; `context.latestVersion` names 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": [
                        "user_not_active",
                        "no_version_in_force"
                      ]
                    },
                    "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 4194304 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
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "`rate_limited`: A limit that keeps the Mindset instance serving you healthy was reached, so the request was refused before any of its body was processed, and nothing was stored. Wait the number of seconds in the `Retry-After` header, then send it again. `message` says which limit (this key's, this Org's share, or the instance being busy) and `context` names it (`limit`, `scope`, `kind`, `value`, `retryAfterSeconds`). A caller that retries at once is refused again.",
            "headers": {
              "Retry-After": {
                "description": "Whole seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 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": [
                        "rate_limited"
                      ]
                    },
                    "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."
      }
    }
  }
}
