---
title: "Execute a skillset ability"
method: POST
path: "/skillset/{skillsetId}/ability/{abilityId}/execute"
tags: ["Skillset Ability"]
---

# Execute a skillset ability

`POST /skillset/{skillsetId}/ability/{abilityId}/execute`

## Request

- Base URL: `https://api.chatbotkit.com/api/v1`
- URL: `https://api.chatbotkit.com/api/v1/skillset/{skillsetId}/ability/{abilityId}/execute`
- Auth: HTTP bearer

Executes a specific ability from a skillset with the provided input.
This endpoint processes the ability's instruction template using the
given input and returns the execution result along with usage statistics.
The response is streamed as JSON lines (JSONL) to support real-time
progress updates during execution.

## Path parameters

- `skillsetId` string, required: The ID of the skillset containing the ability
- `abilityId` string, required: The ID of the ability to execute

## Request body

- object
  - `input` string: The input to process with the ability. This can be structured text such as JSON or YAML for precise parameter control, or unstructured natural language text. When unstructured text is provided, the system will automatically detect and extract the relevant parameters from the input.
  - `contactId` string: The ID of the contact to associate with the execution

## Response `200`

The ability was executed successfully

- object
  - `usage` Usage, required: Usage information
    - `token` number, required: The tokens used in this exchange
  - `error` string: Error message if execution failed
  - `result` unknown
  - `messages` Message[]: Messages generated during execution
    - `type` 'user' | 'bot' | 'reasoning' | 'context' | 'instruction' | 'backstory' | 'activity' | 'checkpoint', required: The type of the message
    - `text` string, required: The text of the message
    - `meta` Meta: Meta data information

## Other responses

- `default`: An error response

---

[API](https://skmtc.dev/chatbotkit/apis/cbk-api.md) · [All operations](https://skmtc.dev/chatbotkit/apis/cbk-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chatbotkit/apis/cbk-api/revisions/13d250576136?raw)