---
title: "Execute a capability"
method: POST
path: "/v1/do"
tags: ["capabilities"]
---

# Execute a capability

`POST /v1/do`

## Request

- Base URL: `https://api.strale.io`
- URL: `https://api.strale.io/v1/do`
- Auth: one of:
  - HTTP bearer
  - none

Execute a Strale capability. Two patterns:

1. **Direct execution**: Provide `capability_slug` and `inputs` to execute a specific capability.
2. **Semantic matching**: Provide `task` as a natural language description — the system finds and executes the best matching capability.

Free-tier capabilities (iban-validate, email-validate, dns-lookup, json-repair, url-to-markdown) work without authentication.

For long-running capabilities (>10s), the response has `status: "pending"` with a `transaction_id`. Poll `GET /v1/transactions/{id}` until `status` is `completed` or `failed`.

Supports `Idempotency-Key` header for safe retries.

## Request body

- DoRequest: Provide either capability_slug (direct execution) or task (semantic matching).
  - `task` string: Natural language task description. The system finds the best matching capability.
  - `capability_slug` string: Direct capability slug to execute.
  - `inputs` object: Capability-specific input fields.
  - `max_price_cents` integer: Maximum price willing to pay (EUR cents). Required for authenticated requests to paid capabilities.
  - `timeout_seconds` integer: Max execution time (1-60, default 30).
  - `dry_run` boolean: If true, returns matched capability without executing.

## Response `200`

Capability executed successfully (synchronous).

- DoResponse: Response from POST /v1/do. Core execution data in `result`, trust metadata in `meta`.
  - `result` object: What the caller asked for — the execution result.
    - `transaction_id` string, uuid
    - `status` 'completed' | 'executing' | 'failed'
    - `capability_used` string
    - `price_cents` integer
    - `latency_ms` integer
    - `wallet_balance_cents` integer: Remaining wallet balance (authenticated only).
    - `output` object, nullable
    - `provenance` object
      - `source` string
      - `fetched_at` string, date-time
  - `meta` object: Per-call audit trail.
    - `audit` object: EU AI Act compliant audit trail.
  - `free_tier` boolean: True for unauthenticated free-tier calls.
  - `usage` object: Free-tier usage counter (unauthenticated only).
  - `upgrade` object: Upgrade prompt with paid capability examples (free-tier only).

## Other responses

- `202`: Capability execution started (asynchronous). Poll GET /v1/transactions/{transaction_id} for result.
- `400`: Missing task or capability_slug.
- `401`: Authentication required for paid capabilities.
- `402`: Insufficient wallet balance. Top up at the included checkout URL.
- `404`: No capability matches the task within budget.
- `429`: Rate limit exceeded.
- `503`: Capability is temporarily unavailable (circuit breaker open).

---

[API](https://skmtc.dev/strale/apis/strale-api-2.md) · [All operations](https://skmtc.dev/strale/apis/strale-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/strale/apis/strale-api-2/revisions/a5293878cfc6?raw)