---
title: "Execute one unified capability"
method: POST
path: "/v1/capabilities/execute"
tags: ["Capability Plane"]
---

# Execute one unified capability

`POST /v1/capabilities/execute`

## Request

- Base URL: `https://api.algenta.ai`
- URL: `https://api.algenta.ai/v1/capabilities/execute`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Executes a capability. If its catalog entry has approval_required=True and no approved plan_id is supplied, this does NOT execute -- it returns a pending plan (status='approval_required' on the receipt, plus plan_id/plan_hash/nonce) instead. Approve it via POST /v1/capability-executions/{plan_id}/approve, then call this endpoint again with plan_id set to actually run it.

## Request body

- CapabilityExecutionRequest
  - `capability_id` string, required
  - `binding_id` string, nullable
  - `input` object, nullable
  - `request_id` string, nullable
  - `plan_id` string, nullable: Reference to a previously proposed capability execution plan (returned as plan_id when an approval_required capability was invoked without a prior approval). Required to actually execute such a capability once its plan has been approved via POST /v1/capability-executions/{plan_id}/approve. Ignored (must be omitted) for capabilities that do not require approval.

## Response `200`

Successful Response

- CapabilityExecutionResponse
  - `execution_session_id` string, required
  - `capability_id` string, required
  - `provider_id` string, required
  - `binding_id` string, required
  - `execution_owner` 'algenta_managed' | 'client_managed', required
  - `status` 'started' | 'succeeded' | 'failed', required
  - `output` object, nullable
  - `error` object, nullable
  - `started_at` string, date-time, required
  - `completed_at` string, date-time, nullable
  - `plan_id` string, nullable: Set when this capability is approval_required: identifies the pending or decided execution plan.
  - `plan_hash` string, nullable: Hash of the proposed plan; an approval is bound to this.
  - `nonce` string, nullable: Single-use approval challenge -- present only when a new plan is proposed.
  - `receipt` object, nullable: The versioned ExecutionReceipt (apps.api_server.schemas.receipt), present once a plan is proposed (status='approval_required') or actually executed (status='executed'/'failed').

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/codna/apis/algenta-api.md) · [All operations](https://skmtc.dev/codna/apis/algenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/codna/apis/algenta-api/revisions/35d30f84a5df?raw)