---
title: "Submit a tool-use intent for asynchronous execution"
method: POST
path: "/v1/executions"
---

# Submit a tool-use intent for asynchronous execution

`POST /v1/executions`

## Request

- Base URL: `https://api.klanexai.com`
- URL: `https://api.klanexai.com/v1/executions`
- Auth: API key in header `X-API-Key`

## Request body

- CreateExecutionRequest
  - `target` Target, required
    - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
    - `url` string, uri, required: Absolute http(s) URL of the third-party API.
    - `headers` object: Your third-party credentials. Encrypted at rest; values are REDACTED in all reads.
    - `connection_id` string: Reference a vault connection; its managed token is injected at execution time instead of passing credentials in headers.
    - `timeout_ms` integer: Per-attempt timeout.
  - `payload` unknown
  - `payload_schema` unknown
  - `callback_url` string, uri
  - `max_attempts` integer
  - `idempotency_key` string: Tenant-scoped; duplicate submits return the original execution.
  - `requires_approval` boolean: Pause in PENDING_APPROVAL until /approve or /reject.

## Response `200`

Idempotent replay: this idempotency_key was already used; the original execution is returned with its current status. Nothing was re-queued.

- AcceptedResponse
  - `execution_id` string
  - `status` 'PENDING_APPROVAL' | 'QUEUED' | 'RUNNING' | 'RETRYING' | 'SUCCEEDED' | 'FAILED'

## Other responses

- `202`: Validated and queued (or paused in PENDING_APPROVAL).
- `400`: Malformed request (bad URL, unsupported method, invalid JSON, bad filter).
- `401`: Missing or invalid X-API-Key.
- `422`: Payload failed the JSON Schema gate. Feed error.llm_hint back to the agent and resubmit.
- `429`: Per-tenant rate limit exceeded; retry after Retry-After seconds.
- `502`: Persisted but could not be enqueued; safe to retry the request.

---

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