---
title: "Reserve an operation"
method: POST
path: "/v1/operations/execute"
---

# Reserve an operation

`POST /v1/operations/execute`

## Request

- Base URL: `https://api.turos.app`
- URL: `https://api.turos.app/v1/operations/execute`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Validates and reserves a channel-neutral operation against the current quote and budget gate, returning an execution envelope (`status: quoted | blocked`). The operation itself is not run and no usage is settled by this call.

## Request body

- object
  - `operationId` string, required
  - `surface` 'api' | 'mcp' | 'cli' | 'excel' | 'sheets' | 'sdk_js' | 'sdk_py' | 'sdk_go' | 'sdk_rust', required
  - `operationSchemaVersion` string, nullable
  - `quoteId` string, nullable
  - `idempotencyKey` string, required
  - `clientId` string, nullable
  - `workbookInstallationId` string, nullable
  - `sourceKey` string, nullable
  - `artifactClass` string, nullable
  - `evidenceRequirement` string, nullable
  - `planKey` string, nullable
  - `meterClass` string, nullable
  - `path` string, nullable
  - `method` string, nullable
  - `units` number, nullable
  - `metadata` object, nullable

## Response `200`

Successful response

- object
  - `object` 'operation_execution', required
  - `executionId` string, required
  - `status` 'quoted' | 'blocked', required
  - `settlementMode` 'shadow', required
  - `operationContext` object, required
    - `operationContextId` string, required
    - `operationId` string, required
    - `operationSchemaVersion` string, required
    - `organizationId` string, required
    - `accountId` string, nullable
    - `userId` string, nullable
    - `clientId` string, nullable
    - `surface` 'api' | 'mcp' | 'cli' | 'excel' | 'sheets' | 'sdk_js' | 'sdk_py' | 'sdk_go' | 'sdk_rust', required
    - `workbookInstallationId` string, nullable
    - `sourceKey` string, nullable
    - `artifactClass` string, nullable
    - `evidenceRequirement` string, nullable
    - `priceVersion` string, required
    - `quoteId` string, required
    - `billableUnits` object[], required
      - `meterClass` string, required
      - `meterFamily` string, required
      - `quantity` number, required
      - `amountCents` integer, required
    - `reservedMaximumCredits` integer, required
    - `idempotencyKey` string, nullable, required
    - `idempotencyMode` 'none' | 'deterministic_shadow', required
    - `createdAt` string, required
  - `billingQuote` object, required
    - `object` 'billing_quote', required
    - `planKey` string, required
    - `meterClass` string, required
    - `meterFamily` string, required
    - `units` integer, required
    - `unitAmountUsd` number, required
    - `amountUsd` number, required
    - `amountCents` integer, required
    - `currency` 'usd', required
    - `requestId` string, required
    - `budget` object, required
    - `budgetGate` object, nullable, required
  - `budgetGate` object, nullable, required
  - `requestId` string, required

## Other responses

- `default`: Contract-aware error response

---

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