---
title: "Invoke Capability"
method: POST
path: "/v1/capabilities/{capability_key}/invoke"
tags: ["public_api", "external"]
---

# Invoke Capability

`POST /v1/capabilities/{capability_key}/invoke`

## Request

- Base URL: `https://api.hydracept.com`
- URL: `https://api.hydracept.com/v1/capabilities/{capability_key}/invoke`
- Auth: HTTP bearer

## Path parameters

- `capability_key` string, required

## Request body

- CapabilityInvokeRequest
  - `externalRef` string, nullable: Opaque caller-owned correlation reference. Never sent to providers. Max 255 characters.
  - `tags` string[]: Caller-owned flat labels for correlation and future exact-match filtering. At most 32 tags; each tag max 256 characters.
  - `metadata` object: Opaque caller-owned JSON bookkeeping. Never interpreted or sent to providers. Serialized size capped at 16384 UTF-8 bytes.
  - `responseSchema` object, nullable
  - `toolSchemas` object[], nullable
  - `sampling` HydraceptSampling: Optional product-requested sampling. Providers that reject custom sampling omit these.
    - `temperature` number, nullable
    - `reasoningIntent` 'omit' | 'economy' | 'balanced' | 'deep' | 'maximum'
  - `readerDelivery` ReaderDelivery: Opt in to partial text output on a durable text job. ``boundary`` is ``paragraph``: events close on a blank line, or on a sentence-sized span once the hold limit is reached. Tokens are not events.
    - `boundary` 'paragraph'
  - `maturityRating` 'G' | 'PG' | 'PG13' | 'R' | 'NC17'
  - `matureContentTraits` MatureContentTrait[]
  - `maturitySource` 'explicit_invocation' | 'project_default' | 'workload_derived' | 'legacy_default'
  - `context` CapabilityContext
    - `productId` string
    - `environment` string
    - `projectId` string, nullable
    - `dataClassification` 'Public' | 'Internal' | 'Confidential' | 'PrivateUserContent' | 'Manuscript'
    - `retentionRequirement` 'HashesOnly' | 'Transient' | 'EncryptedShortTerm' | 'ProductManaged' | 'ProductionAsset'
  - `input` object
  - `inputPayloadRef` string, nullable: Verified payload id from POST /v1/payloads. When set, inline input is optional; the server resolves content before admission, estimate, and stream dispatch.
  - `execution` CapabilityExecutionOptions
    - `executionPreference` string
    - `billingMode` string, nullable
    - `credentialSource` string, nullable
    - `quoteId` string, nullable
    - `estimateId` string, nullable: Inbound alias of quoteId. Prefer quoteId and pricing.quote.
    - `maximumCharge` object, nullable
    - `executionConstraints` ExecutionConstraints
      - `maxCostUsd` number, nullable
      - `providerPin` string, nullable
      - `preferredModel` string, nullable
      - `autoSelect` boolean: Opt in to smart fallback when preferredModel is physically unavailable. Ignored when preferredModel is omitted.
      - `budgetEnforcement` string, nullable: warn (admit over ceiling) or prevent (HTTP 402). Setting maxCostUsd without this is prevent.
      - `maxDurationSeconds` integer, nullable: Provider execution deadline in seconds after the job starts running. Does not include queue wait. timeoutSeconds is accepted as an alias.
  - `idempotencyKey` string, nullable
  - `correlationId` string, nullable
  - `taskKind` string, nullable
  - `executionMode` 'RequestResponse' | 'Stream' | 'DurableJob' | 'ProductionWorkflow'
  - `pin` ExactTargetPin: Exact execution target. Hydracept does not substitute.
    - `target` string, required

## Response `200`

Successful response

- HydraceptInvocationResult
  - `executionId` string, required
  - `idempotencyKey` string, nullable
  - `status` string, required
  - `resolvedProvider` string, nullable
  - `resolvedModel` string, nullable
  - `selectedCandidateId` string, nullable
  - `servedCandidateId` string, nullable
  - `credentialMode` string, nullable
  - `credentialSource` string, nullable
  - `externalRef` string, nullable
  - `tags` string[]
  - `metadata` object
  - `typedOutput` unknown
  - `outputPayloadRef` string, nullable
  - `generatedArtifacts` string[]
  - `usage` HydraceptUsageSummary
    - `inputTokens` integer, nullable
    - `outputTokens` integer, nullable
    - `estimatedCost` number, nullable
    - `actualCost` number
    - `currency` string
  - `actualCost` number
  - `terminationReason` string, nullable
  - `receiptId` string, nullable
  - `errorCode` string, nullable
  - `dispatchStatus` string, nullable
  - `warnings` object[]

## Other responses

- `401`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `402`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `403`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `404`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `409`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `422`: Validation failure: public envelope plus Pydantic `detail` / `validationErrors`
- `429`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `500`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `502`: Structured public error envelope (`code`, `message`, `requestId`, …)
- `503`: Structured public error envelope (`code`, `message`, `requestId`, …)

---

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