# `GET /v1/skills` — List skills to call

Part of the [Bkper Managed Agent API](https://bkper.com/docs/api/managed-agent.md). Read its guide for authentication, conventions, and examples.

The skills the user may call by name (`/<name>`) in a session starting now, sorted by name: their company's, their own and, with `bookId`, that Book's, merged as a session loads them, those kept to explicit use included. As published, never the sandbox's working copy, and never starting it: once a session has loaded its context, its own `skills` say what it may call. A scope that is slow, fails or cannot be read (a Book the user cannot view) is left out, never an error. Read as the user in every workspace, an app's included.

## Operation contract

```json
{
  "operationId": "listSkills",
  "tags": [
    "Sessions"
  ],
  "summary": "List skills to call",
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "bookId",
      "in": "query",
      "schema": {
        "type": "string",
        "pattern": "^[A-Za-z0-9_-]{1,128}$"
      },
      "description": "The Book a session would start in."
    }
  ],
  "description": "The skills the user may call by name (`/<name>`) in a session starting now, sorted by name: their company's, their own and, with `bookId`, that Book's, merged as a session loads them, those kept to explicit use included. As published, never the sandbox's working copy, and never starting it: once a session has loaded its context, its own `skills` say what it may call. A scope that is slow, fails or cannot be read (a Book the user cannot view) is left out, never an error. Read as the user in every workspace, an app's included.",
  "responses": {
    "200": {
      "description": "Success",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SkillList"
          }
        }
      }
    },
    "400": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "410": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "411": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "413": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "Rejected; never contains credentials or upstream payloads.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    }
  }
}
```

## Schemas

### SkillList

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "What the person types after `/` to call it."
          },
          "description": {
            "type": "string"
          },
          "scope": {
            "type": "string",
            "description": "Whose context it comes from, as in `contextScopes`: on a name, the Book's wins over the user's, and the user's over the company's. Open: domain | user | book."
          },
          "bookId": {
            "description": "The Book, for its scope.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "description",
          "scope"
        ]
      }
    }
  },
  "required": [
    "items"
  ]
}
```

### Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable code, e.g. not_found, idempotency_conflict, session_working, usage_limit_exceeded. Open."
        },
        "type": {
          "description": "Category, e.g. invalid_request_error, authentication_error, usage_limit_error. Open.",
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "host": {
          "description": "host_in_use: the host another service holds.",
          "type": "string"
        },
        "service": {
          "description": "host_in_use: the id of the service that holds the host.",
          "type": "string"
        },
        "reason": {
          "description": "file_invalid: why the change, or a picture, was refused. Open: path | text | size | skill | skills | count | type.",
          "type": "string"
        },
        "paths": {
          "description": "file_exists from an add: every path of the request where a file is and `replace` was not set, all at once, so the person can be asked once. publish_conflict: the files someone published changes to the same lines of.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "publishers": {
          "description": "publish_conflict: who published those changes, by name.",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "code"
      ]
    }
  },
  "required": [
    "error"
  ]
}
```

## Authentication

```json
{
  "bearerAuth": {
    "type": "http",
    "scheme": "bearer"
  }
}
```