CapabilityInvokeRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hydracept-com/json-schema/hydracept-com-capability-invoke-request-schema.json",
  "title": "CapabilityInvokeRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hydracept-com-openapi.json#/components/schemas/CapabilityInvokeRequest",
  "properties": {
    "externalRef": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 255
        },
        {
          "type": "null"
        }
      ],
      "title": "Externalref",
      "description": "Opaque caller-owned correlation reference. Never sent to providers. Max 255 characters."
    },
    "tags": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "maxItems": 32,
      "title": "Tags",
      "description": "Caller-owned flat labels for correlation and future exact-match filtering. At most 32 tags; each tag max 256 characters."
    },
    "metadata": {
      "additionalProperties": true,
      "type": "object",
      "title": "Metadata",
      "description": "Opaque caller-owned JSON bookkeeping. Never interpreted or sent to providers. Serialized size capped at 16384 UTF-8 bytes."
    },
    "responseSchema": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "title": "Responseschema"
    },
    "toolSchemas": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Toolschemas"
    },
    "sampling": {
      "anyOf": [
        {
          "$ref": "#/$defs/HydraceptSampling"
        },
        {
          "type": "null"
        }
      ]
    },
    "readerDelivery": {
      "anyOf": [
        {
          "$ref": "#/$defs/ReaderDelivery"
        },
        {
          "type": "null"
        }
      ],
      "description": "On a durable text job, publish job.reader_text events during the one provider call, before the receipt is sealed. Replay with GET /v1/jobs/{jobId}/events?type=job.reader_text. Not streaming invoke. Uses standard processing. Does not change the selected route."
    },
    "maturityRating": {
      "anyOf": [
        {
          "$ref": "#/$defs/MaturityRating"
        },
        {
          "type": "null"
        }
      ]
    },
    "matureContentTraits": {
      "items": {
        "$ref": "#/$defs/MatureContentTrait"
      },
      "type": "array",
      "title": "Maturecontenttraits"
    },
    "maturitySource": {
      "anyOf": [
        {
          "$ref": "#/$defs/MaturitySource"
        },
        {
          "type": "null"
        }
      ]
    },
    "context": {
      "$ref": "#/$defs/CapabilityContext"
    },
    "input": {
      "additionalProperties": true,
      "type": "object",
      "title": "Input"
    },
    "inputPayloadRef": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Inputpayloadref",
      "description": "Verified payload id from POST /v1/payloads. When set, inline input is optional; the server resolves content before admission, estimate, and stream dispatch."
    },
    "execution": {
      "$ref": "#/$defs/CapabilityExecutionOptions"
    },
    "idempotencyKey": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Idempotencykey"
    },
    "correlationId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Correlationid"
    },
    "taskKind": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Taskkind"
    },
    "executionMode": {
      "anyOf": [
        {
          "$ref": "#/$defs/ExecutionMode"
        },
        {
          "type": "null"
        }
      ]
    },
    "pin": {
      "anyOf": [
        {
          "$ref": "#/$defs/ExactTargetPin"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false,
  "type": "object",
  "$defs": {
    "CapabilityContext": {
      "properties": {
        "productId": {
          "type": "string",
          "title": "Productid",
          "default": ""
        },
        "environment": {
          "type": "string",
          "title": "Environment",
          "default": ""
        },
        "projectId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Projectid"
        },
        "dataClassification": {
          "$ref": "#/$defs/DataClassification",
          "default": "Internal"
        },
        "retentionRequirement": {
          "$ref": "#/$defs/RetentionPolicy",
          "default": "Transient"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "CapabilityContext"
    },
    "CapabilityExecutionOptions": {
      "properties": {
        "executionPreference": {
          "type": "string",
          "title": "Executionpreference",
          "default": "automatic"
        },
        "billingMode": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Billingmode"
        },
        "credentialSource": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Credentialsource"
        },
        "quoteId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Quoteid"
        },
        "estimateId": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Estimateid",
          "description": "Inbound alias of quoteId. Prefer quoteId and pricing.quote."
        },
        "maximumCharge": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Maximumcharge"
        },
        "executionConstraints": {
          "anyOf": [
            {
              "$ref": "#/$defs/ExecutionConstraints"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "CapabilityExecutionOptions"
    },
    "DataClassification": {
      "type": "string",
      "enum": [
        "Public",
        "Internal",
        "Confidential",
        "PrivateUserContent",
        "Manuscript"
      ],
      "title": "DataClassification"
    },
    "ExactTargetPin": {
      "properties": {
        "target": {
          "type": "string",
          "title": "Target"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "target"
      ],
      "title": "ExactTargetPin",
      "description": "Exact execution target. Hydracept does not substitute."
    },
    "ExecutionConstraints": {
      "properties": {
        "maxCostUsd": {
          "anyOf": [
            {
              "type": "number",
              "exclusiveMinimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Maxcostusd"
        },
        "providerPin": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Providerpin",
          "description": "Hard provider pin: one authorized model and no substitution. Use modelSelection mode ordered or prefer when fallback is intended."
        },
        "preferredModel": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Preferredmodel",
          "description": "Legacy hard pin. An ineligible model fails the request; this field does not authorize substitution. Use modelSelection for exact, ordered, prefer, or auto selection."
        },
        "autoSelect": {
          "type": "boolean",
          "title": "Autoselect",
          "description": "Opt in to physical-unavailability fallback for preferredModel. This does not authorize substitution for content or a mandatory execution requirement. Ignored when preferredModel is omitted.",
          "default": false
        },
        "modelSelection": {
          "anyOf": [
            {
              "$ref": "#/$defs/ModelSelection"
            },
            {
              "type": "null"
            }
          ],
          "description": "Ordered model-selection contract: exact, ordered, prefer, or auto. Cannot be combined with preferredModel or autoSelect."
        },
        "budgetEnforcement": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Budgetenforcement",
          "description": "warn (admit over ceiling) or prevent (HTTP 402). Setting maxCostUsd without this is prevent."
        },
        "maxDurationSeconds": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 7200.0,
              "minimum": 5.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Maxdurationseconds",
          "description": "Provider execution deadline in seconds after the job starts running. Does not include queue wait. timeoutSeconds is accepted as an alias."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "ExecutionConstraints"
    },
    "ExecutionMode": {
      "type": "string",
      "enum": [
        "RequestResponse",
        "Stream",
        "DurableJob",
        "ProductionWorkflow"
      ],
      "title": "ExecutionMode"
    },
    "HydraceptReasoningIntent": {
      "type": "string",
      "enum": [
        "omit",
        "economy",
        "balanced",
        "deep",
        "maximum"
      ],
      "title": "HydraceptReasoningIntent"
    },
    "HydraceptSampling": {
      "properties": {
        "temperature": {
          "anyOf": [
            {
              "type": "number",
              "maximum": 2.0,
              "minimum": 0.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Temperature"
        },
        "reasoningIntent": {
          "anyOf": [
            {
              "$ref": "#/$defs/HydraceptReasoningIntent"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "HydraceptSampling",
      "description": "Optional product-requested sampling. Providers that reject custom sampling omit these."
    },
    "MatureContentTrait": {
      "type": "string",
      "enum": [
        "sexual_non_graphic",
        "sexual_explicit",
        "graphic_violence"
      ],
      "title": "MatureContentTrait"
    },
    "MaturityRating": {
      "type": "string",
      "enum": [
        "G",
        "PG",
        "PG13",
        "R",
        "NC17"
      ],
      "title": "MaturityRating"
    },
    "MaturitySource": {
      "type": "string",
      "enum": [
        "explicit_invocation",
        "project_default",
        "workload_derived",
        "legacy_default"
      ],
      "title": "MaturitySource"
    },
    "ModelSelection": {
      "properties": {
        "mode": {
          "$ref": "#/$defs/ModelSelectionMode",
          "default": "prefer"
        },
        "models": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "maxItems": 8,
          "title": "Models",
          "description": "Ordered model references, each 'model' or 'provider:model'."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "ModelSelection",
      "description": "One ordered model preference contract.\n\n``models`` is ordered. For ``exact`` it must contain exactly one entry; for\n``ordered`` every entry is an authorized fallback; for ``prefer`` the first\nentry is the preference and later entries are explicit fallbacks tried\nbefore Hydracept's own eligible ordering. ``auto`` carries no explicit\nmodels because the caller delegates identity entirely."
    },
    "ModelSelectionMode": {
      "type": "string",
      "enum": [
        "exact",
        "ordered",
        "prefer",
        "auto"
      ],
      "title": "ModelSelectionMode"
    },
    "ReaderDelivery": {
      "properties": {
        "boundary": {
          "$ref": "#/$defs/ReaderDeliveryBoundary",
          "default": "paragraph"
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "ReaderDelivery",
      "description": "Opt in to partial text output on a durable text job.\n\n``boundary`` is ``paragraph``: events close on a blank line, or on a\nsentence-sized span once the hold limit is reached. Tokens are not events."
    },
    "ReaderDeliveryBoundary": {
      "type": "string",
      "enum": [
        "paragraph"
      ],
      "title": "ReaderDeliveryBoundary"
    },
    "RetentionPolicy": {
      "type": "string",
      "enum": [
        "HashesOnly",
        "Transient",
        "EncryptedShortTerm",
        "ProductManaged",
        "ProductionAsset"
      ],
      "title": "RetentionPolicy"
    }
  }
}