> This page is optimized for agents. Use the linked Markdown pages and llms.txt indexes for related API content.

# Run any ability by id

> The original envelope: the same as POST /v1/abilities/{id}, with the ability named in the body.

- Product: Meta
- Section: meta
- Snapshot: v0.1.0+8bf142be
- Method: `POST`
- Path: `/abilities/execute`

## Request body

Required: yes  
Content types: `application/json`  

### `ability`

Type: `string`  
Required: yes  
Allowed values: `capability.discover`, `connection.authorize`, `connection.get`, `connection.list`, `connection.revoke`, `contact.create`, `contact.get`, `contact.list`, `contact.update`, `decision.list`, `decision.record`, `document.generate`, `document.summarize`, `email.render`, `event.emit`, `file.store`, `guide.list`, `guide.publish`, `integration.app.connect`, `integration.app.connections`, `integration.app.execute`, `integration.app.toolkits`, `integration.app.tools`, `integration.execute`, `integration.search`, `key.inspect`, `key.issue`, `key.list`, `key.revoke`, `key.rotate`, `lead.create`, `lead.get`, `lead.list`, `lead.update_status`, `lesson.record`, `memory.forget`, `memory.recall`, `memory.save`, `memory.search`, `message.send`, `message.send_markdown`, `payment.initiate`, `payment.list`, `payment.status`, `payout.balance`, `payout.batch`, `payout.list`, `payout.send`, `payout.status`, `payout.verify_account`, `plan.create`, `plan.execute`, `plan.learn`, `plan.verify`, `qa.browser_check`, `qa.checklist.create`, `research.verify`, `sim.generate`, `sim.list`, `skill.list`, `skill.load`, `task.create`, `task.get`, `task.list`, `task.update_status`, `trust.preflight`, `trust.publish`, `trust.status`, `vertical.list`, `vertical.manifest_get`, `web.browse`, `web.research`, `workflow.trigger`, `workspace.doc.close`, `workspace.doc.comment`, `workspace.doc.create`, `workspace.doc.list`, `workspace.doc.patch`, `workspace.doc.read`  

### `input`

Type: `object`  
Required: yes  

Matches the named ability's input schema.

### `context`

Type: `CallContext`  
Required: no  

Optional call context. The tenant always comes from the credential: `tenantId` is honoured only by a credential allowed to address sub-tenants, and then nests under the credential's own tenant.

#### `tenantId`

Type: `string`  
Required: no  

Sub-tenant to act for (sub-tenant credentials only).

#### `runId`

Type: `string`  
Required: no  

The trust run (from trust.preflight) this call executes under.

#### `verticalId`

Type: `string`  
Required: no  

Vertical to attribute created records to.

## Execute with curl

```bash
curl -X POST https://substrate.sloelabs.com/abilities/execute \
    -H "Authorization: Bearer $SLOE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{"ability":"capability.discover","input":{}}'
```

## Execute with JavaScript

```js
const response = await fetch("https://substrate.sloelabs.com/abilities/execute", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SLOE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ability": "capability.discover",
    "input": {}
  }),
});
const { ok, result, error } = await response.json();
```

## Execute with Python

```python
import os
import requests

response = requests.post(
    "https://substrate.sloelabs.com/abilities/execute",
    headers={"Authorization": f"Bearer {os.environ['SLOE_API_KEY']}"},
    json={
        "ability": "capability.discover",
        "input": {},
    },
)
print(response.json())
```

## Responses

### Response `200`

Category: success  

The ability ran.

#### `application/json`

Documentation payload key: `result`  

##### Generated example

```json
{
  "ok": true,
  "ability": "ability",
  "duration": 0
}
```

##### Schema

###### AbilityResult

Type: `AbilityResult`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `ability`

Type: `string`  
Required: yes  

The ability that ran.

###### `result`

Type: `unknown`  
Required: yes  

The ability's return value. Its shape depends on the ability.

###### `duration`

Type: `number`  
Required: yes  

Server-side execution time, in milliseconds.

### Response `400`

Category: client-error  

Missing or unknown ability, or input that fails its schema.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `401`

Category: client-error  

No bearer credential, or one the substrate does not recognise.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `403`

Category: client-error  

The credential is valid, but its scope does not include this ability.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `429`

Category: client-error  

Too many requests for this credential. `retryAfterMs` says when to retry.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `501`

Category: server-error  

The ability is declared but no handler is wired.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

### Response `default`

Category: default  

The ability failed. The message is sanitized; a 5xx may be a transient upstream failure.

#### `application/json`

##### Generated example

```json
{
  "ok": true,
  "error": "error",
  "ability": "ability",
  "reason": "reason",
  "details": [
    {}
  ],
  "retryAfterMs": 0
}
```

##### Schema

###### ErrorResponse

Type: `ErrorResponse`  

###### `ok`

Type: `boolean`  
Required: yes  

###### `error`

Type: `string`  
Required: yes  

###### `ability`

Type: `string`  
Required: no  

###### `reason`

Type: `string`  
Required: no  

###### `details`

Type: `object[]`  
Required: no  

JSON Schema validation errors.

###### object

Type: `object`  

###### `code`

Type: `unknown`  
Required: no  

A machine-readable error code, when the ability sets one.

###### `retryAfterMs`

Type: `number`  
Required: no  

## Related representations

- [Human documentation](/api/meta/methods/execute/)
- [curl Markdown](/api/meta/methods/execute.md?lang=curl)
- [JavaScript Markdown](/api/meta/methods/execute.md?lang=fetch)
- [Python Markdown](/api/meta/methods/execute.md?lang=python)
- [site llms.txt](/api/llms.txt)
- [product llms.txt](/api/meta/llms.txt)
- [snapshot llms.txt](/api/meta/llms.txt)