{
"components": {
"parameters": {
"ProjectID": {
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
"ToolHookID": {
"in": "path",
"name": "hook_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
"WebhookID": {
"in": "path",
"name": "webhook_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"schemas": {
"APIError": {
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"code",
"message"
],
"type": "object"
},
"AuthResponse": {
"properties": {
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"tokens": {
"$ref": "#/components/schemas/AuthTokens"
},
"user": {
"$ref": "#/components/schemas/User"
}
},
"type": "object"
},
"AuthTokens": {
"properties": {
"access_token": {
"type": "string"
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"refresh_token": {
"type": "string"
}
},
"type": "object"
},
"BillingMode": {
"description": "Billing mode for a project. 'managed' uses ModelRelay billing with tiers and subscriptions. 'byob' (Bring Your Own Billing) allows external billing.",
"enum": [
"managed",
"byob"
],
"type": "string"
},
"BillingProvider": {
"description": "Billing provider backing the subscription or tier.",
"enum": [
"stripe",
"crypto",
"app_store",
"external"
],
"type": "string"
},
"ChangeTierRequest": {
"properties": {
"tier_code": {
"description": "The tier code to switch to",
"type": "string"
}
},
"required": [
"tier_code"
],
"type": "object"
},
"CheckoutSessionResponse": {
"properties": {
"session_id": {
"description": "Stripe checkout session ID",
"type": "string"
},
"url": {
"description": "Checkout URL",
"format": "uri",
"type": "string"
}
},
"required": [
"session_id",
"url"
],
"type": "object"
},
"Citation": {
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"ContentPart": {
"properties": {
"text": {
"type": "string"
},
"type": {
"enum": [
"text"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"Customer": {
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"email": {
"description": "Customer email address",
"format": "email",
"type": "string"
},
"external_id": {
"description": "External customer identifier from your system",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"metadata": {
"$ref": "#/components/schemas/CustomerMetadata"
},
"project_id": {
"format": "uuid",
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"CustomerBalanceResponse": {
"properties": {
"balance_cents": {
"format": "int64",
"minimum": 0,
"type": "integer"
},
"billing_profile_id": {
"description": "Billing profile UUID for wallet/balance.",
"format": "uuid",
"type": "string"
},
"currency": {
"type": "string"
},
"customer_id": {
"description": "Internal customer UUID (identity).",
"format": "uuid",
"type": "string"
},
"reserved_cents": {
"format": "int64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"customer_id",
"billing_profile_id",
"balance_cents",
"reserved_cents",
"currency"
],
"type": "object"
},
"CustomerCreate": {
"properties": {
"email": {
"description": "Customer email address",
"format": "email",
"type": "string"
},
"external_id": {
"description": "External customer identifier from your system",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"metadata": {
"$ref": "#/components/schemas/CustomerMetadata"
}
},
"required": [
"external_id",
"email"
],
"type": "object"
},
"CustomerLedgerEntry": {
"properties": {
"amount_cents": {
"format": "int64",
"type": "integer"
},
"balance_after_cents": {
"format": "int64",
"type": "integer"
},
"credit_amount_cents": {
"format": "int64",
"type": "integer"
},
"description": {
"type": "string"
},
"direction": {
"type": "string"
},
"gross_amount_cents": {
"format": "int64",
"type": "integer"
},
"id": {
"format": "uuid",
"type": "string"
},
"input_tokens": {
"format": "int64",
"type": "integer"
},
"model_id": {
"$ref": "#/components/schemas/ModelId"
},
"occurred_at": {
"format": "date-time",
"type": "string"
},
"output_tokens": {
"format": "int64",
"type": "integer"
},
"owner_revenue_cents": {
"format": "int64",
"type": "integer"
},
"platform_fee_cents": {
"format": "int64",
"type": "integer"
},
"reason": {
"type": "string"
},
"request_id": {
"format": "uuid",
"type": "string"
},
"stripe_checkout_session_id": {
"type": "string"
},
"stripe_invoice_id": {
"type": "string"
},
"stripe_payment_intent_id": {
"type": "string"
}
},
"required": [
"id",
"direction",
"reason",
"amount_cents",
"description",
"occurred_at"
],
"type": "object"
},
"CustomerLedgerResponse": {
"properties": {
"entries": {
"items": {
"$ref": "#/components/schemas/CustomerLedgerEntry"
},
"type": "array"
}
},
"required": [
"entries"
],
"type": "object"
},
"CustomerMe": {
"properties": {
"customer": {
"$ref": "#/components/schemas/Customer"
},
"subscription": {
"$ref": "#/components/schemas/Subscription"
},
"tier": {
"$ref": "#/components/schemas/Tier"
}
},
"required": [
"customer"
],
"type": "object"
},
"CustomerMeCheckoutRequest": {
"properties": {
"cancel_url": {
"description": "URL to redirect to if checkout is cancelled",
"format": "uri",
"type": "string"
},
"success_url": {
"description": "URL to redirect to after successful checkout",
"format": "uri",
"type": "string"
},
"tier_code": {
"description": "The tier code to subscribe to",
"type": "string"
}
},
"required": [
"tier_code",
"success_url",
"cancel_url"
],
"type": "object"
},
"CustomerMeResponse": {
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerMe"
}
},
"required": [
"customer"
],
"type": "object"
},
"CustomerMeSubscription": {
"description": "Customer-visible subscription details for the current tier.",
"properties": {
"current_period_end": {
"description": "End of the current billing period",
"format": "date-time",
"type": "string"
},
"current_period_start": {
"description": "Start of the current billing period",
"format": "date-time",
"type": "string"
},
"price_amount_cents": {
"description": "Subscription price amount in cents (omitted for free tiers)",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"price_currency": {
"description": "Currency code for the price (e.g., 'usd')",
"type": "string"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"subscription_status": {
"$ref": "#/components/schemas/SubscriptionStatusKind"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"tier_display_name": {
"description": "Human-readable tier name",
"maxLength": 255,
"minLength": 1,
"type": "string"
}
},
"required": [
"tier_code",
"tier_display_name"
],
"type": "object"
},
"CustomerMeSubscriptionResponse": {
"properties": {
"subscription": {
"$ref": "#/components/schemas/CustomerMeSubscription"
}
},
"required": [
"subscription"
],
"type": "object"
},
"CustomerMeUsage": {
"description": "Customer-visible usage metrics for the current billing window.",
"properties": {
"daily": {
"items": {
"$ref": "#/components/schemas/CustomerUsagePoint"
},
"type": "array"
},
"images": {
"format": "int64",
"minimum": 0,
"type": "integer"
},
"low": {
"description": "True when 80% or more of spend limit is used (nil if unlimited)",
"type": "boolean"
},
"overage_enabled": {
"description": "True when PAYGO wallet can cover subscription overages",
"type": "boolean"
},
"percentage_used": {
"description": "Percentage of spend limit used (nil if unlimited)",
"format": "float",
"maximum": 100,
"minimum": 0,
"type": "number"
},
"requests": {
"format": "int64",
"minimum": 0,
"type": "integer"
},
"tokens": {
"format": "int64",
"minimum": 0,
"type": "integer"
},
"total_cost_cents": {
"description": "Total cost incurred in this billing window (always populated)",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"spend_limit_cents": {
"description": "API usage budget for this billing window (nil if unlimited)",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"spend_remaining_cents": {
"description": "Remaining budget (spend_limit_cents minus total_cost_cents, nil if unlimited)",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"wallet_balance_cents": {
"description": "PAYGO wallet balance in cents (available when PAYGO wallet is enabled)",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"wallet_reserved_cents": {
"description": "PAYGO wallet reserved amount in cents",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"window_end": {
"description": "End of the current billing window",
"format": "date-time",
"type": "string"
},
"window_start": {
"description": "Start of the current billing window",
"format": "date-time",
"type": "string"
}
},
"required": [
"window_start",
"window_end",
"requests",
"tokens",
"images",
"total_cost_cents",
"daily"
],
"type": "object"
},
"CustomerMeUsageResponse": {
"properties": {
"usage": {
"$ref": "#/components/schemas/CustomerMeUsage"
}
},
"required": [
"usage"
],
"type": "object"
},
"CustomerMetadata": {
"additionalProperties": true,
"description": "Arbitrary customer metadata (max 10KB). Keys are limited to 40 characters. Values can be any JSON type. Nesting depth limited to 5 levels.",
"type": "object"
},
"CustomerTokenResponse": {
"properties": {
"billing_profile_id": {
"description": "Billing profile UUID for managed billing customers.",
"format": "uuid",
"type": "string"
},
"customer_external_id": {
"description": "External customer identifier",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"customer_id": {
"description": "Internal customer UUID (identity).",
"format": "uuid",
"type": "string"
},
"expires_at": {
"description": "Token expiration timestamp",
"format": "date-time",
"type": "string"
},
"expires_in": {
"description": "Seconds until token expires",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"project_id": {
"description": "Project the token is scoped to",
"format": "uuid",
"type": "string"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"token": {
"description": "The customer bearer token",
"type": "string"
}
},
"required": [
"token",
"expires_at",
"expires_in",
"project_id",
"customer_external_id",
"customer_id"
],
"type": "object"
},
"CustomerTopupRequest": {
"properties": {
"cancel_url": {
"format": "uri",
"type": "string"
},
"credit_amount_cents": {
"format": "int64",
"minimum": 1,
"type": "integer"
},
"success_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"credit_amount_cents",
"success_url",
"cancel_url"
],
"type": "object"
},
"CustomerTopupResponse": {
"properties": {
"checkout_url": {
"format": "uri",
"type": "string"
},
"credit_amount_cents": {
"format": "int64",
"type": "integer"
},
"gross_amount_cents": {
"format": "int64",
"type": "integer"
},
"owner_revenue_cents": {
"format": "int64",
"type": "integer"
},
"platform_fee_cents": {
"format": "int64",
"type": "integer"
},
"session_id": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"session_id",
"checkout_url",
"gross_amount_cents",
"credit_amount_cents",
"owner_revenue_cents",
"platform_fee_cents",
"status"
],
"type": "object"
},
"AutoTopupPaymentMethod": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"brand": {
"type": "string"
},
"last4": {
"type": "string"
},
"exp_month": {
"type": "integer",
"format": "int64"
},
"exp_year": {
"type": "integer",
"format": "int64"
}
},
"required": [
"id",
"brand",
"last4",
"exp_month",
"exp_year"
]
},
"AutoTopupLimits": {
"type": "object",
"properties": {
"min_topup_cents": {
"type": "integer",
"format": "int64"
},
"max_single_cents": {
"type": "integer",
"format": "int64"
},
"max_daily_cents": {
"type": "integer",
"format": "int64"
},
"max_monthly_cents": {
"type": "integer",
"format": "int64"
}
},
"required": [
"min_topup_cents",
"max_single_cents",
"max_daily_cents",
"max_monthly_cents"
]
},
"AutoTopupConfigResponse": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"threshold_cents": {
"type": "integer",
"format": "int64"
},
"amount_cents": {
"type": "integer",
"format": "int64"
},
"payment_method": {
"$ref": "#/components/schemas/AutoTopupPaymentMethod"
},
"failure_count": {
"type": "integer"
},
"last_triggered_at": {
"type": "string",
"format": "date-time"
},
"limits": {
"$ref": "#/components/schemas/AutoTopupLimits"
}
},
"required": [
"enabled",
"threshold_cents",
"amount_cents",
"failure_count",
"limits"
]
},
"AutoTopupSetupResponse": {
"type": "object",
"properties": {
"setup_intent_id": {
"type": "string"
},
"client_secret": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"setup_intent_id",
"client_secret"
]
},
"AutoTopupConfigRequest": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"threshold_cents": {
"type": "integer",
"format": "int64"
},
"amount_cents": {
"type": "integer",
"format": "int64"
}
},
"required": [
"enabled",
"threshold_cents",
"amount_cents"
]
},
"AutoTopupConfirmRequest": {
"type": "object",
"properties": {
"setup_intent_id": {
"type": "string"
}
},
"required": [
"setup_intent_id"
]
},
"CustomerUsagePoint": {
"properties": {
"day": {
"description": "UTC day bucket",
"format": "date-time",
"type": "string"
},
"images": {
"format": "int64",
"minimum": 0,
"type": "integer"
},
"requests": {
"format": "int64",
"minimum": 0,
"type": "integer"
},
"tokens": {
"format": "int64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"day",
"requests",
"tokens"
],
"type": "object"
},
"CustomerWithSubscription": {
"properties": {
"billing_customer_id": {
"description": "Billing provider customer ID (e.g., Stripe customer ID)",
"type": "string"
},
"customer": {
"$ref": "#/components/schemas/Customer"
},
"subscription": {
"$ref": "#/components/schemas/Subscription"
}
},
"required": [
"customer"
],
"type": "object"
},
"ImageData": {
"description": "A single generated image.",
"properties": {
"b64_json": {
"description": "Base64-encoded image data (when response_format is 'b64_json')",
"type": "string"
},
"expires_at": {
"description": "When the image URL expires (null if pinned)",
"format": "date-time",
"type": "string"
},
"image_id": {
"description": "Unique identifier for the image (used for pinning)",
"type": "string"
},
"mime_type": {
"description": "MIME type of the image (e.g., 'image/png', 'image/webp')",
"type": "string"
},
"pin_url": {
"description": "URL to pin this image for permanent storage",
"type": "string"
},
"url": {
"description": "URL of the generated image (when response_format is 'url')",
"type": "string"
}
},
"type": "object"
},
"ImagePinResponse": {
"description": "Response from pin/unpin operations.",
"properties": {
"expires_at": {
"description": "When the image expires (null if pinned)",
"format": "date-time",
"type": "string"
},
"id": {
"description": "Image ID",
"type": "string"
},
"pinned": {
"description": "Whether the image is currently pinned",
"type": "boolean"
},
"url": {
"description": "URL of the image",
"type": "string"
}
},
"required": [
"id",
"pinned",
"url"
],
"type": "object"
},
"ImageRequest": {
"description": "Request to generate images from a text prompt.",
"properties": {
"model": {
"description": "Image generation model ID (e.g., gemini-2.5-flash-image). Optional when using a customer token with a tier that defines a default model.",
"type": "string"
},
"n": {
"default": 1,
"description": "Number of images to generate (1-10, default 1)",
"maximum": 10,
"minimum": 1,
"type": "integer"
},
"prompt": {
"description": "Text description of the image to generate",
"type": "string"
},
"response_format": {
"$ref": "#/components/schemas/ImageResponseFormat"
}
},
"required": [
"prompt"
],
"type": "object"
},
"ImageResponse": {
"description": "Response containing generated images.",
"properties": {
"data": {
"description": "Generated images",
"items": {
"$ref": "#/components/schemas/ImageData"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this generation request",
"type": "string"
},
"model": {
"description": "Model used for generation",
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/ImageUsage"
}
},
"required": [
"id",
"model",
"data",
"usage"
],
"type": "object"
},
"ImageResponseFormat": {
"default": "url",
"description": "Output format for generated images.",
"enum": [
"url",
"b64_json"
],
"type": "string"
},
"ImageUsage": {
"description": "Usage statistics for image generation.",
"properties": {
"images": {
"description": "Number of images generated",
"format": "int32",
"type": "integer"
}
},
"required": [
"images"
],
"type": "object"
},
"InputItem": {
"properties": {
"content": {
"items": {
"$ref": "#/components/schemas/ContentPart"
},
"type": "array"
},
"role": {
"$ref": "#/components/schemas/MessageRole"
},
"tool_call_id": {
"$ref": "#/components/schemas/ToolCallId"
},
"tool_calls": {
"items": {
"$ref": "#/components/schemas/ToolCall"
},
"type": "array"
},
"type": {
"enum": [
"message"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"JSONPatchOperation": {
"properties": {
"from": {
"type": "string"
},
"op": {
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"type": "string"
},
"path": {
"type": "string"
},
"value": {
"additionalProperties": true,
"type": "object"
}
},
"required": [
"op",
"path"
],
"type": "object"
},
"JSONSchemaFormat": {
"properties": {
"description": {
"type": "string"
},
"name": {
"type": "string"
},
"schema": {
"additionalProperties": true,
"type": "object"
},
"strict": {
"type": "boolean"
}
},
"required": [
"name"
],
"type": "object"
},
"MessageRole": {
"enum": [
"system",
"user",
"assistant",
"tool"
],
"type": "string"
},
"Model": {
"properties": {
"capabilities": {
"items": {
"$ref": "#/components/schemas/ModelCapability"
},
"type": "array"
},
"context_window": {
"format": "int32",
"minimum": 0,
"type": "integer"
},
"deprecated": {
"type": "boolean"
},
"deprecation_message": {
"type": "string"
},
"description": {
"type": "string"
},
"display_name": {
"type": "string"
},
"input_cost_per_million_cents": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"max_output_tokens": {
"format": "int32",
"minimum": 0,
"type": "integer"
},
"model_id": {
"$ref": "#/components/schemas/ModelId"
},
"output_cost_per_million_cents": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"training_cutoff": {
"description": "Training cutoff in YYYY-MM format",
"type": "string"
}
},
"required": [
"model_id",
"provider",
"display_name",
"description",
"capabilities",
"context_window",
"max_output_tokens",
"training_cutoff",
"deprecated",
"deprecation_message",
"input_cost_per_million_cents",
"output_cost_per_million_cents"
],
"type": "object"
},
"ModelCapability": {
"description": "Workflow-critical model capability identifier.",
"enum": [
"text_generation",
"tools",
"vision",
"web_search",
"web_fetch",
"computer_use",
"code_execution",
"image_generation"
],
"type": "string"
},
"ModelId": {
"description": "LLM model identifier (e.g., claude-sonnet-4-5, gpt-4o).",
"maxLength": 128,
"minLength": 1,
"type": "string"
},
"ModelsResponse": {
"properties": {
"models": {
"items": {
"$ref": "#/components/schemas/Model"
},
"type": "array"
}
},
"required": [
"models"
],
"type": "object"
},
"NDJSONStreamEvent": {
"description": "Events sent during streaming responses (application/x-ndjson).\nEach line is a JSON object with an \"event\" field indicating the type.\n",
"properties": {
"event": {
"description": "Event type",
"enum": [
"message_start",
"message_delta",
"message_stop",
"tool_use_start",
"tool_use_delta",
"tool_use_stop",
"ping",
"keepalive"
],
"type": "string"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"state_id": {
"format": "uuid",
"type": "string"
},
"response_id": {
"description": "Response identifier (message_start)",
"type": "string"
},
"stop_reason": {
"description": "Why generation stopped (message_stop)",
"type": "string"
},
"text_delta": {
"description": "Text content fragment (message_delta)",
"type": "string"
},
"tool_call_delta": {
"$ref": "#/components/schemas/ToolCallDelta"
},
"tool_calls": {
"description": "Completed tool calls (tool_use_stop, message_stop)",
"items": {
"$ref": "#/components/schemas/ToolCall"
},
"type": "array"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
},
"required": [
"event"
],
"type": "object"
},
"NodeErrorV0": {
"properties": {
"code": {
"type": "string"
},
"detail": {
"description": "Raw error details from the provider",
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"NodeId": {
"description": "Workflow node identifier. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.",
"maxLength": 64,
"minLength": 1,
"pattern": "^[a-z][a-z0-9_]*$",
"type": "string"
},
"NodeResultV0": {
"properties": {
"ended_at": {
"format": "date-time",
"type": "string"
},
"error": {
"$ref": "#/components/schemas/NodeErrorV0"
},
"id": {
"$ref": "#/components/schemas/NodeId"
},
"output": {
"additionalProperties": true,
"type": "object"
},
"started_at": {
"format": "date-time",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/NodeStatusV0"
},
"type": {
"$ref": "#/components/schemas/NodeTypeV0"
}
},
"required": [
"id",
"type",
"status"
],
"type": "object"
},
"NodeStatusV0": {
"enum": [
"pending",
"running",
"waiting",
"succeeded",
"failed",
"canceled"
],
"type": "string"
},
"NodeTypeV0": {
"description": "Type of workflow node.",
"enum": [
"llm.responses",
"route.switch",
"join.all",
"join.any",
"join.collect",
"map.fanout",
"transform.json"
],
"type": "string"
},
"OutboundWebhookEvent": {
"properties": {
"attempt_count": {
"format": "int32",
"type": "integer"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"error": {
"type": "string"
},
"event_id": {
"type": "string"
},
"event_type": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"last_attempt_at": {
"format": "date-time",
"type": "string"
},
"latency_ms": {
"format": "int32",
"type": "integer"
},
"next_attempt_at": {
"format": "date-time",
"type": "string"
},
"payload": {
"type": "object"
},
"response_body": {
"type": "string"
},
"response_status": {
"format": "int32",
"type": "integer"
},
"status": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
},
"webhook_config_id": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"OutputFormat": {
"properties": {
"json_schema": {
"$ref": "#/components/schemas/JSONSchemaFormat"
},
"type": {
"enum": [
"text",
"json_schema"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"OutputItem": {
"properties": {
"content": {
"items": {
"$ref": "#/components/schemas/ContentPart"
},
"type": "array"
},
"role": {
"$ref": "#/components/schemas/MessageRole"
},
"tool_calls": {
"items": {
"$ref": "#/components/schemas/ToolCall"
},
"type": "array"
},
"type": {
"enum": [
"message"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"PlanHash": {
"description": "SHA-256 hash of the compiled workflow plan (64 hex characters).",
"maxLength": 64,
"minLength": 64,
"pattern": "^[a-f0-9]{64}$",
"type": "string"
},
"PluginAgentV0": {
"properties": {
"name": {
"type": "string"
},
"system_prompt": {
"type": "string"
}
},
"required": [
"name",
"system_prompt"
],
"type": "object"
},
"PluginCommandV0": {
"properties": {
"agent_refs": {
"items": {
"type": "string"
},
"type": "array"
},
"name": {
"type": "string"
},
"prompt": {
"type": "string"
}
},
"required": [
"name",
"prompt"
],
"type": "object"
},
"PluginGitHubRefV0": {
"properties": {
"owner": {
"type": "string"
},
"path": {
"type": "string"
},
"ref": {
"type": "string"
},
"repo": {
"type": "string"
}
},
"type": "object"
},
"PluginManifestV0": {
"properties": {
"agents": {
"items": {
"type": "string"
},
"type": "array"
},
"commands": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "string"
}
},
"type": "object"
},
"PluginSummaryV0": {
"properties": {
"agents": {
"items": {
"$ref": "#/components/schemas/PluginAgentV0"
},
"type": "array"
},
"description": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"agents",
"name"
],
"type": "object"
},
"PluginsCompileRequest": {
"description": "Request to compile a Claude Code plugin into a workflow. One of source or files must be provided (mutually exclusive).",
"properties": {
"content": {
"description": "Deprecated. Use files instead.",
"type": "string"
},
"files": {
"additionalProperties": {
"type": "string"
},
"description": "Map of file paths to content for inline plugins (e.g., .claude-plugin/plugin.json, agents/worker.md). Mutually exclusive with source.",
"type": "object"
},
"max_attempts": {
"default": 3,
"maximum": 5,
"minimum": 1,
"type": "integer"
},
"mode": {
"description": "Compile mode. Currently only 'intent' is supported.",
"enum": ["intent"],
"default": "intent",
"type": "string"
},
"model": {
"type": "string"
},
"source": {
"description": "GitHub URL to fetch plugin from (e.g., github:owner/repo@ref). Mutually exclusive with files.",
"type": "string"
}
},
"type": "object"
},
"PluginsCompileResponse": {
"properties": {
"compiled_at": {
"format": "date-time",
"type": "string"
},
"plugin": {
"$ref": "#/components/schemas/PluginSummaryV0"
},
"source_ref": {
"type": "string"
},
"workflow": {
"$ref": "#/components/schemas/WorkflowSpec"
}
},
"required": [
"compiled_at",
"plugin",
"source_ref",
"workflow"
],
"type": "object"
},
"PriceInterval": {
"description": "Billing interval for a tier.",
"enum": [
"month",
"year"
],
"type": "string"
},
"Project": {
"properties": {
"billing_mode": {
"$ref": "#/components/schemas/BillingMode"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"description": {
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"markup_percentage": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"name": {
"type": "string"
},
"owner_id": {
"format": "uuid",
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"ProviderId": {
"description": "LLM provider identifier.",
"enum": [
"anthropic",
"openai",
"xai",
"google-ai-studio"
],
"type": "string"
},
"RequestId": {
"description": "Unique identifier for an LLM request within a workflow run.",
"format": "uuid",
"type": "string"
},
"ResponsesBatchError": {
"properties": {
"code": {
"type": "string"
},
"detail": {
"description": "Raw error details from the provider",
"type": "string"
},
"message": {
"type": "string"
},
"status": {
"type": "integer"
}
},
"required": [
"status",
"message"
],
"type": "object"
},
"ResponsesBatchRequest": {
"properties": {
"options": {
"properties": {
"abort_on_error": {
"type": "boolean"
},
"max_parallelism": {
"format": "uint32",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
"type": "object"
},
"requests": {
"items": {
"$ref": "#/components/schemas/ResponsesRequest"
},
"type": "array"
}
},
"required": [
"requests"
],
"type": "object"
},
"ResponsesBatchResponse": {
"properties": {
"request_id": {
"type": "string"
},
"results": {
"items": {
"$ref": "#/components/schemas/ResponsesBatchResult"
},
"type": "array"
}
},
"required": [
"results"
],
"type": "object"
},
"ResponsesBatchResult": {
"properties": {
"error": {
"$ref": "#/components/schemas/ResponsesBatchError"
},
"index": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"ok": {
"type": "boolean"
},
"response": {
"$ref": "#/components/schemas/ResponsesResponse"
}
},
"required": [
"index",
"ok"
],
"type": "object"
},
"ResponsesRequest": {
"properties": {
"input": {
"items": {
"$ref": "#/components/schemas/InputItem"
},
"type": "array"
},
"max_output_tokens": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"state_id": {
"format": "uuid",
"type": "string"
},
"output_format": {
"$ref": "#/components/schemas/OutputFormat"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"stop": {
"items": {
"type": "string"
},
"type": "array"
},
"temperature": {
"type": "number"
},
"tool_choice": {
"$ref": "#/components/schemas/ToolChoice"
},
"tools": {
"items": {
"$ref": "#/components/schemas/Tool"
},
"type": "array"
}
},
"required": [
"input"
],
"type": "object"
},
"ResponsesResponse": {
"properties": {
"citations": {
"description": "Sources from web search results",
"items": {
"$ref": "#/components/schemas/Citation"
},
"type": "array"
},
"id": {
"description": "Response identifier from the provider",
"type": "string"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"output": {
"items": {
"$ref": "#/components/schemas/OutputItem"
},
"type": "array"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"stop_reason": {
"description": "Why generation stopped (stop, max_tokens, tool_use, etc.)",
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
},
"required": [
"id",
"output",
"model",
"usage"
],
"type": "object"
},
"StateHandleCreateRequest": {
"properties": {
"ttl_seconds": {
"description": "TTL in seconds for the state handle. Maximum is 1 year (31536000 seconds).",
"format": "int64",
"minimum": 1,
"maximum": 31536000,
"type": "integer"
}
},
"type": "object"
},
"StateHandleResponse": {
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"project_id": {
"format": "uuid",
"type": "string"
},
"customer_id": {
"format": "uuid",
"type": "string"
},
"created_at": {
"type": "string"
},
"expires_at": {
"type": "string"
}
},
"required": [
"id",
"project_id",
"created_at"
],
"type": "object"
},
"StateHandleListResponse": {
"properties": {
"state_handles": {
"items": {
"$ref": "#/components/schemas/StateHandleResponse"
},
"type": "array"
},
"next_cursor": {
"type": "string"
}
},
"required": [
"state_handles"
],
"type": "object"
},
"ResponsesStreamEnvelope": {
"properties": {
"code": {
"type": "string"
},
"complete_fields": {
"items": {
"type": "string"
},
"type": "array"
},
"content": {
"type": "string"
},
"delta": {
"type": "string"
},
"message": {
"type": "string"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"patch": {
"items": {
"$ref": "#/components/schemas/JSONPatchOperation"
},
"type": "array"
},
"payload": {
"additionalProperties": true,
"type": "object"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"request_id": {
"type": "string"
},
"status": {
"type": "integer"
},
"stop_reason": {
"type": "string"
},
"stream_mode": {
"enum": [
"text-delta",
"structured-patch"
],
"type": "string"
},
"stream_version": {
"enum": [
"v2"
],
"type": "string"
},
"type": {
"enum": [
"start",
"update",
"completion",
"error",
"keepalive",
"tool_use_start",
"tool_use_delta",
"tool_use_stop"
],
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
},
"required": [
"type"
],
"type": "object"
},
"RunCostLineItemV0": {
"properties": {
"input_tokens": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"output_tokens": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"provider_id": {
"$ref": "#/components/schemas/ProviderId"
},
"requests": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"usd_cents": {
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"provider_id",
"model",
"requests",
"input_tokens",
"output_tokens",
"usd_cents"
],
"type": "object"
},
"RunCostSummaryV0": {
"properties": {
"line_items": {
"items": {
"$ref": "#/components/schemas/RunCostLineItemV0"
},
"type": "array"
},
"total_usd_cents": {
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"required": [
"total_usd_cents"
],
"type": "object"
},
"RunId": {
"description": "Unique identifier for a workflow run.",
"format": "uuid",
"type": "string"
},
"RunStatusV0": {
"enum": [
"running",
"waiting",
"succeeded",
"failed",
"canceled"
],
"type": "string"
},
"RunsCreateOptionsV0": {
"properties": {
"idempotency_key": {
"type": "string"
}
},
"type": "object"
},
"RunsCreateRequest": {
"description": "Create a workflow run. The workflow spec must include a resolved model for every llm.responses/route.switch node (including map.fanout subnodes); /runs does not resolve tiers or default models. Use model_override or model_overrides to override models at runtime.",
"properties": {
"input": {
"additionalProperties": true,
"description": "Runtime inputs for the workflow. Required when the spec uses from_input references (e.g., map.fanout with items.from_input). Each key is the input name, and the value is the JSON data to provide.",
"type": "object"
},
"model_override": {
"description": "Default model override applied to all llm.responses and route.switch nodes (including map.fanout subnodes) unless overridden by model_overrides.",
"type": "string"
},
"model_overrides": {
"description": "Per-node model overrides. Use nodes for top-level nodes and fanout_subnodes for map.fanout subnodes.",
"type": "object",
"properties": {
"nodes": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"fanout_subnodes": {
"type": "array",
"items": {
"type": "object",
"required": [
"parent_id",
"subnode_id",
"model"
],
"properties": {
"parent_id": {
"type": "string"
},
"subnode_id": {
"type": "string"
},
"model": {
"type": "string"
}
}
}
}
}
},
"stream": {
"description": "When true, overrides all llm.responses and route.switch nodes to stream (emit node_output_delta events). When false or omitted, uses the workflow spec defaults.",
"type": "boolean"
},
"options": {
"$ref": "#/components/schemas/RunsCreateOptionsV0"
},
"session_id": {
"description": "Optional session ID to link this run to a session.",
"format": "uuid",
"type": "string"
},
"spec": {
"$ref": "#/components/schemas/WorkflowSpec"
}
},
"required": [
"spec"
],
"type": "object"
},
"RunsCreateResponse": {
"properties": {
"plan_hash": {
"$ref": "#/components/schemas/PlanHash"
},
"run_id": {
"$ref": "#/components/schemas/RunId"
},
"status": {
"$ref": "#/components/schemas/RunStatusV0"
}
},
"required": [
"run_id",
"status",
"plan_hash"
],
"type": "object"
},
"RunsGetResponse": {
"properties": {
"cost_summary": {
"$ref": "#/components/schemas/RunCostSummaryV0"
},
"nodes": {
"items": {
"$ref": "#/components/schemas/NodeResultV0"
},
"type": "array"
},
"outputs": {
"additionalProperties": true,
"type": "object"
},
"steps": {
"items": {
"$ref": "#/components/schemas/RunNodeStepsV0"
},
"type": "array"
},
"plan_hash": {
"$ref": "#/components/schemas/PlanHash"
},
"run_id": {
"$ref": "#/components/schemas/RunId"
},
"parent_run_id": {
"$ref": "#/components/schemas/RunId"
},
"summary": {
"$ref": "#/components/schemas/RunSummary"
},
"status": {
"$ref": "#/components/schemas/RunStatusV0"
}
},
"required": [
"run_id",
"status",
"plan_hash",
"cost_summary",
"summary"
],
"type": "object"
},
"RunSummary": {
"properties": {
"total_steps": {
"minimum": 0,
"type": "integer"
},
"total_llm_calls": {
"minimum": 0,
"type": "integer"
},
"total_tool_calls": {
"minimum": 0,
"type": "integer"
},
"total_input_tokens": {
"minimum": 0,
"type": "integer"
},
"total_output_tokens": {
"minimum": 0,
"type": "integer"
},
"total_cost_cents": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"total_steps",
"total_llm_calls",
"total_tool_calls",
"total_input_tokens",
"total_output_tokens",
"total_cost_cents"
],
"type": "object"
},
"RunStepDetail": {
"properties": {
"node_id": {
"type": "string"
},
"step": {
"minimum": 0,
"type": "integer"
},
"request_id": {
"format": "uuid",
"type": "string"
},
"llm_call": {
"additionalProperties": true,
"type": "object"
},
"llm_request": {
"additionalProperties": true,
"type": "object"
},
"llm_response": {
"additionalProperties": true,
"type": "object"
},
"tool_calls": {
"items": {
"$ref": "#/components/schemas/RunsPendingToolCallV0"
},
"type": "array"
},
"tool_results": {
"items": {
"$ref": "#/components/schemas/RunToolResultV0"
},
"type": "array"
}
},
"required": [
"node_id",
"step"
],
"type": "object"
},
"RunStepsResponse": {
"properties": {
"steps": {
"items": {
"$ref": "#/components/schemas/RunStepDetail"
},
"type": "array"
}
},
"type": "object"
},
"RunTaskStatus": {
"enum": [
"pending",
"in_progress",
"completed"
],
"type": "string"
},
"RunTask": {
"properties": {
"content": {
"type": "string"
},
"status": {
"$ref": "#/components/schemas/RunTaskStatus"
},
"active_form": {
"type": "string"
}
},
"required": [
"content",
"status"
],
"type": "object"
},
"RunTasksResponse": {
"properties": {
"tasks": {
"items": {
"$ref": "#/components/schemas/RunTask"
},
"type": "array"
}
},
"type": "object"
},
"RunToolCallDetail": {
"properties": {
"node_id": {
"type": "string"
},
"step": {
"minimum": 0,
"type": "integer"
},
"tool_call": {
"properties": {
"arguments": {
"description": "JSON-encoded arguments for the tool call",
"type": "string"
},
"id": {
"$ref": "#/components/schemas/ToolCallId"
},
"name": {
"$ref": "#/components/schemas/ToolName"
}
},
"required": [
"id",
"name",
"arguments"
],
"type": "object"
},
"tool_result": {
"$ref": "#/components/schemas/RunToolResultV0"
}
},
"required": [
"node_id",
"step",
"tool_call"
],
"type": "object"
},
"Agent": {
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"project_id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"current_revision": {
"type": "integer"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"project_id",
"name",
"slug",
"current_revision",
"created_at",
"updated_at"
],
"type": "object"
},
"AgentFragmentRef": {
"properties": {
"ref": {
"type": "string"
},
"inputs": {
"additionalProperties": {
"type": "string"
},
"type": "object"
}
},
"required": [
"ref"
],
"type": "object"
},
"AgentToolRef": {
"properties": {
"hook_id": {
"format": "uuid",
"type": "string"
},
"definition": {
"$ref": "#/components/schemas/Tool"
},
"fragment": {
"$ref": "#/components/schemas/AgentFragmentRef"
}
},
"type": "object"
},
"AgentVersion": {
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"agent_id": {
"format": "uuid",
"type": "string"
},
"revision": {
"type": "integer"
},
"system": {
"type": "string"
},
"model": {
"type": "string"
},
"tools": {
"items": {
"$ref": "#/components/schemas/AgentToolRef"
},
"type": "array"
},
"fragments": {
"additionalProperties": true,
"type": "object"
},
"max_steps": {
"type": "integer"
},
"max_duration_sec": {
"type": "integer"
},
"step_timeout_sec": {
"type": "integer"
},
"tool_failure_policy": {
"enum": [
"stop",
"continue",
"retry"
],
"type": "string"
},
"tool_retry_count": {
"type": "integer"
},
"created_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"agent_id",
"revision",
"system",
"tools",
"max_steps",
"max_duration_sec",
"step_timeout_sec",
"tool_failure_policy",
"tool_retry_count",
"created_at"
],
"type": "object"
},
"AgentResource": {
"properties": {
"agent": {
"$ref": "#/components/schemas/Agent"
},
"version": {
"$ref": "#/components/schemas/AgentVersion"
}
},
"required": [
"agent",
"version"
],
"type": "object"
},
"AgentListResponse": {
"properties": {
"agents": {
"items": {
"$ref": "#/components/schemas/AgentResource"
},
"type": "array"
}
},
"type": "object"
},
"AgentResponse": {
"properties": {
"agent": {
"$ref": "#/components/schemas/AgentResource"
}
},
"type": "object"
},
"AgentCreateRequest": {
"properties": {
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"system": {
"type": "string"
},
"model": {
"type": "string"
},
"tools": {
"items": {
"$ref": "#/components/schemas/AgentToolRef"
},
"type": "array"
},
"fragments": {
"additionalProperties": true,
"type": "object"
},
"max_steps": {
"type": "integer"
},
"max_duration_sec": {
"type": "integer"
},
"step_timeout_sec": {
"type": "integer"
},
"tool_failure_policy": {
"enum": [
"stop",
"continue",
"retry"
],
"type": "string"
},
"tool_retry_count": {
"type": "integer"
}
},
"required": [
"name",
"slug"
],
"type": "object"
},
"AgentUpdateRequest": {
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"system": {
"type": "string"
},
"model": {
"type": "string"
},
"tools": {
"items": {
"$ref": "#/components/schemas/AgentToolRef"
},
"type": "array"
},
"fragments": {
"additionalProperties": true,
"type": "object"
},
"max_steps": {
"type": "integer"
},
"max_duration_sec": {
"type": "integer"
},
"step_timeout_sec": {
"type": "integer"
},
"tool_failure_policy": {
"enum": [
"stop",
"continue",
"retry"
],
"type": "string"
},
"tool_retry_count": {
"type": "integer"
}
},
"type": "object"
},
"AgentRunOptions": {
"properties": {
"max_steps": {
"type": "integer"
},
"max_duration_sec": {
"type": "integer"
},
"step_timeout_sec": {
"type": "integer"
},
"tool_failure_policy": {
"enum": [
"stop",
"continue",
"retry"
],
"type": "string"
},
"tool_retry_count": {
"type": "integer"
},
"model": {
"type": "string"
},
"stream": {
"type": "boolean"
},
"capture_tool_io": {
"type": "boolean"
},
"dry_run": {
"type": "boolean"
}
},
"type": "object"
},
"AgentRunRequest": {
"properties": {
"input": {
"items": {
"$ref": "#/components/schemas/InputItem"
},
"type": "array"
},
"options": {
"$ref": "#/components/schemas/AgentRunOptions"
},
"customer_id": {
"type": "string"
}
},
"required": [
"input"
],
"type": "object"
},
"AgentTestRequest": {
"properties": {
"input": {
"items": {
"$ref": "#/components/schemas/InputItem"
},
"type": "array"
},
"mock_tools": {
"additionalProperties": true,
"type": "object"
},
"options": {
"$ref": "#/components/schemas/AgentRunOptions"
}
},
"required": [
"input"
],
"type": "object"
},
"AgentRunResponse": {
"properties": {
"run_id": {
"$ref": "#/components/schemas/RunId"
},
"output": {
"items": {
"$ref": "#/components/schemas/OutputItem"
},
"type": "array"
},
"usage": {
"$ref": "#/components/schemas/RunSummary"
},
"steps": {
"items": {
"$ref": "#/components/schemas/RunStepDetail"
},
"type": "array"
}
},
"required": [
"run_id",
"usage"
],
"type": "object"
},
"RunNodeStepLLMCallV0": {
"description": "Per-step LLM call metadata.",
"properties": {
"model": {
"$ref": "#/components/schemas/ModelId"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"response_id": {
"type": "string"
},
"stop_reason": {
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
},
"type": "object"
},
"RunNodeStepV0": {
"description": "Step-level execution details for a node.",
"properties": {
"llm_call": {
"$ref": "#/components/schemas/RunNodeStepLLMCallV0"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
},
"step": {
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"tool_calls": {
"items": {
"$ref": "#/components/schemas/RunsPendingToolCallV0"
},
"type": "array"
},
"tool_results": {
"items": {
"$ref": "#/components/schemas/RunToolResultV0"
},
"type": "array"
},
"waiting": {
"$ref": "#/components/schemas/RunNodeStepWaitingV0"
}
},
"required": [
"step",
"request_id"
],
"type": "object"
},
"RunNodeStepWaitingV0": {
"description": "Waiting details for a step when client tools are pending.",
"properties": {
"pending_tool_calls": {
"items": {
"$ref": "#/components/schemas/RunsPendingToolCallV0"
},
"type": "array"
},
"reason": {
"type": "string"
}
},
"type": "object"
},
"RunNodeStepsV0": {
"description": "Step history for a node in a workflow run.",
"properties": {
"node_id": {
"$ref": "#/components/schemas/NodeId"
},
"steps": {
"items": {
"$ref": "#/components/schemas/RunNodeStepV0"
},
"type": "array"
}
},
"required": [
"node_id",
"steps"
],
"type": "object"
},
"RunToolResultV0": {
"description": "Result for a tool call executed during a run.",
"properties": {
"error": {
"type": "string"
},
"output": {
"type": "string"
},
"tool_call": {
"properties": {
"arguments": {
"description": "JSON-encoded arguments for the tool call",
"type": "string"
},
"id": {
"$ref": "#/components/schemas/ToolCallId"
},
"name": {
"$ref": "#/components/schemas/ToolName"
}
},
"required": [
"id",
"name"
],
"type": "object"
}
},
"required": [
"tool_call",
"output"
],
"type": "object"
},
"RunsPendingToolCallV0": {
"description": "A pending tool call waiting for a result.",
"properties": {
"tool_call": {
"properties": {
"arguments": {
"description": "JSON-encoded arguments for the tool call",
"type": "string"
},
"id": {
"$ref": "#/components/schemas/ToolCallId"
},
"name": {
"$ref": "#/components/schemas/ToolName",
"description": "Name of the tool to be called"
}
},
"required": [
"id",
"name",
"arguments"
],
"type": "object"
}
},
"required": [
"tool_call"
],
"type": "object"
},
"RunsPendingToolsNodeV0": {
"description": "A node with pending tool calls.",
"properties": {
"node_id": {
"$ref": "#/components/schemas/NodeId"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
},
"step": {
"description": "The step number within the node execution",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"tool_calls": {
"items": {
"$ref": "#/components/schemas/RunsPendingToolCallV0"
},
"type": "array"
}
},
"required": [
"node_id",
"step",
"request_id"
],
"type": "object"
},
"RunsPendingToolsResponse": {
"description": "Response containing pending tool calls for a workflow run.",
"properties": {
"pending": {
"items": {
"$ref": "#/components/schemas/RunsPendingToolsNodeV0"
},
"type": "array"
},
"run_id": {
"$ref": "#/components/schemas/RunId"
}
},
"required": [
"run_id"
],
"type": "object"
},
"SessionCreateRequest": {
"description": "Request body for creating a session.",
"properties": {
"customer_id": {
"description": "Optional customer ID to associate with the session",
"format": "uuid",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "Optional metadata for the session",
"type": "object"
}
},
"type": "object"
},
"SessionListResponse": {
"description": "Paginated list of sessions.",
"properties": {
"next_cursor": {
"description": "Cursor for fetching the next page (if more results exist)",
"type": "string"
},
"sessions": {
"description": "List of sessions",
"items": {
"$ref": "#/components/schemas/SessionResponse"
},
"type": "array"
}
},
"required": [
"sessions"
],
"type": "object"
},
"SessionMessageCreateRequest": {
"description": "Request body for appending a message to a session.",
"properties": {
"content": {
"description": "Message content parts",
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"role": {
"description": "Message role (user, assistant, tool)",
"type": "string"
},
"run_id": {
"description": "Run ID that generated this message (for assistant messages)",
"format": "uuid",
"type": "string"
}
},
"required": [
"role",
"content"
],
"type": "object"
},
"SessionMessageResponse": {
"description": "A message within a session.",
"properties": {
"content": {
"description": "Message content parts",
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"created_at": {
"description": "Message creation timestamp",
"format": "date-time",
"type": "string"
},
"id": {
"description": "Message unique identifier",
"format": "uuid",
"type": "string"
},
"role": {
"description": "Message role (user, assistant, tool)",
"type": "string"
},
"run_id": {
"description": "Run ID that generated this message (for assistant messages)",
"format": "uuid",
"type": "string"
},
"seq": {
"description": "Sequence number within the session",
"format": "int32",
"type": "integer"
}
},
"required": [
"id",
"seq",
"role",
"content",
"created_at"
],
"type": "object"
},
"SessionResponse": {
"description": "A session resource.",
"properties": {
"created_at": {
"description": "Session creation timestamp",
"format": "date-time",
"type": "string"
},
"customer_id": {
"description": "Customer associated with the session (if any)",
"format": "uuid",
"type": "string"
},
"id": {
"description": "Session unique identifier",
"format": "uuid",
"type": "string"
},
"message_count": {
"description": "Number of messages in the session",
"format": "int64",
"type": "integer"
},
"metadata": {
"additionalProperties": true,
"description": "Session metadata",
"type": "object"
},
"project_id": {
"description": "Project the session belongs to",
"format": "uuid",
"type": "string"
},
"updated_at": {
"description": "Session last update timestamp",
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"project_id",
"metadata",
"message_count",
"created_at",
"updated_at"
],
"type": "object"
},
"SessionUpdateRequest": {
"description": "Request body for updating session metadata. Null values remove keys.",
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Metadata fields to set or remove",
"type": "object"
}
},
"required": [
"metadata"
],
"type": "object"
},
"SessionWithMessagesResponse": {
"allOf": [
{
"$ref": "#/components/schemas/SessionResponse"
},
{
"properties": {
"messages": {
"description": "All messages in the session",
"items": {
"$ref": "#/components/schemas/SessionMessageResponse"
},
"type": "array"
}
},
"required": [
"messages"
],
"type": "object"
}
],
"description": "A session with its full message history.",
"type": "object"
},
"Sha256Hash": {
"description": "SHA-256 hash (64 hex characters).",
"maxLength": 64,
"minLength": 64,
"pattern": "^[a-f0-9]{64}$",
"type": "string"
},
"Subscription": {
"properties": {
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"billing_subscription_id": {
"description": "Billing subscription ID from the provider",
"type": "string"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"current_period_end": {
"description": "End of the current billing period",
"format": "date-time",
"type": "string"
},
"current_period_start": {
"description": "Start of the current billing period",
"format": "date-time",
"type": "string"
},
"customer_id": {
"format": "uuid",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"project_id": {
"format": "uuid",
"type": "string"
},
"subscription_status": {
"$ref": "#/components/schemas/SubscriptionStatusKind"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"tier_id": {
"format": "uuid",
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"SubscriptionStatus": {
"description": "Subscription status for a customer.",
"properties": {
"active": {
"description": "Whether the subscription is currently active",
"type": "boolean"
},
"current_period_end": {
"description": "End of the current billing period",
"format": "date-time",
"type": "string"
},
"current_period_start": {
"description": "Start of the current billing period",
"format": "date-time",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/SubscriptionStatusKind"
},
"subscription_id": {
"description": "Stripe subscription ID",
"type": "string"
}
},
"required": [
"active"
],
"type": "object"
},
"SubscriptionStatusKind": {
"description": "Subscription status (active, past_due, canceled, etc.)",
"enum": [
"active",
"trialing",
"past_due",
"canceled",
"unpaid",
"incomplete",
"incomplete_expired",
"paused"
],
"type": "string",
"x-rust-type": {
"crate": "modelrelay",
"path": "modelrelay::SubscriptionStatusKind",
"version": "0.1"
}
},
"Tier": {
"properties": {
"billing_mode": {
"$ref": "#/components/schemas/TierBillingMode"
},
"billing_price_ref": {
"description": "Billing provider price reference for this tier",
"type": "string"
},
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"display_name": {
"description": "Human-readable tier name",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"models": {
"items": {
"$ref": "#/components/schemas/TierModel"
},
"minItems": 1,
"type": "array"
},
"price_amount_cents": {
"description": "Subscription price amount in cents",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"price_currency": {
"description": "Currency code for the price (e.g., 'usd')",
"type": "string"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"project_id": {
"format": "uuid",
"type": "string"
},
"spend_limit_cents": {
"description": "Monthly spend limit in cents (e.g., 2000 = $20/month). Must be non-negative.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"trial_days": {
"description": "Number of trial days for new subscriptions",
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"TierBillingMode": {
"description": "Billing mode for a tier. 'subscription' uses monthly spend limits; 'paygo' uses prepaid balances.",
"enum": [
"subscription",
"paygo"
],
"type": "string"
},
"TierCode": {
"description": "Tier code identifier (e.g., free, pro, enterprise).",
"maxLength": 64,
"minLength": 1,
"pattern": "^[a-z][a-z0-9_-]*$",
"type": "string"
},
"TierCreate": {
"properties": {
"billing_mode": {
"$ref": "#/components/schemas/TierBillingMode"
},
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"display_name": {
"description": "Human-readable tier name",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"models": {
"items": {
"$ref": "#/components/schemas/TierModelCreate"
},
"minItems": 1,
"type": "array"
},
"price_amount_cents": {
"description": "Subscription price amount in cents (paid tiers)",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"spend_limit_cents": {
"description": "Monthly spend limit in cents (e.g., 2000 = $20/month). Must be non-negative.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"trial_days": {
"description": "Number of trial days for new subscriptions (paid tiers)",
"format": "uint32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"tier_code",
"display_name",
"spend_limit_cents",
"models"
],
"type": "object"
},
"TierModel": {
"properties": {
"capabilities": {
"description": "Workflow-critical capability flags for the model",
"items": {
"$ref": "#/components/schemas/ModelCapability"
},
"type": "array"
},
"context_window": {
"description": "Maximum supported context window in tokens (if known)",
"format": "int32",
"minimum": 0,
"type": "integer"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"deprecated": {
"description": "Whether the model is deprecated",
"type": "boolean"
},
"description": {
"description": "Human-friendly description of what the model is good at",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"is_default": {
"description": "Whether this is the default model for the tier",
"type": "boolean"
},
"max_output_tokens": {
"description": "Maximum supported output tokens (if known)",
"format": "int32",
"minimum": 0,
"type": "integer"
},
"model_display_name": {
"description": "Human-friendly model name resolved from pricing (e.g., 'GPT-4o Mini')",
"type": "string"
},
"model_id": {
"$ref": "#/components/schemas/ModelId"
},
"model_input_cost_cents": {
"description": "Provider input cost in cents per million tokens. Customer price is derived as cost * (1 + platformFeePercent/100).",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"model_output_cost_cents": {
"description": "Provider output cost in cents per million tokens. Customer price is derived as cost * (1 + platformFeePercent/100).",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"tier_id": {
"format": "uuid",
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"tier_id",
"model_id",
"model_display_name",
"description",
"capabilities",
"context_window",
"max_output_tokens",
"deprecated",
"model_input_cost_cents",
"model_output_cost_cents",
"is_default",
"created_at",
"updated_at"
],
"type": "object"
},
"TierModelCreate": {
"description": "Model to add to a tier. Pricing is derived from the model_pricing table.",
"properties": {
"is_default": {
"default": false,
"type": "boolean"
},
"model_id": {
"$ref": "#/components/schemas/ModelId"
}
},
"required": [
"model_id"
],
"type": "object"
},
"TierUpdate": {
"properties": {
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"display_name": {
"description": "Human-readable tier name",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"models": {
"items": {
"$ref": "#/components/schemas/TierModelCreate"
},
"minItems": 1,
"type": "array"
},
"price_amount_cents": {
"description": "Subscription price amount in cents (paid tiers)",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"spend_limit_cents": {
"description": "Monthly spend limit in cents (e.g., 2000 = $20/month). Must be non-negative.",
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"trial_days": {
"description": "Number of trial days for new subscriptions (paid tiers)",
"format": "uint32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"tier_code",
"display_name",
"spend_limit_cents"
],
"type": "object"
},
"Tool": {
"properties": {
"code_execution": {
"additionalProperties": true,
"type": "object"
},
"function": {
"properties": {
"description": {
"type": "string"
},
"name": {
"$ref": "#/components/schemas/ToolName"
},
"parameters": {
"additionalProperties": true,
"type": "object"
}
},
"type": "object"
},
"image_generation": {
"description": "Configuration for server-side image generation tool",
"properties": {
"model": {
"description": "Image generation model ID (e.g., gemini-2.5-flash-image)",
"type": "string"
}
},
"required": [
"model"
],
"type": "object"
},
"type": {
"enum": [
"function",
"web",
"x_search",
"code_execution",
"image_generation"
],
"type": "string"
},
"web": {
"additionalProperties": true,
"type": "object"
},
"x_search": {
"additionalProperties": true,
"type": "object"
}
},
"required": [
"type"
],
"type": "object"
},
"ToolCall": {
"properties": {
"function": {
"properties": {
"arguments": {
"description": "JSON string of function arguments",
"type": "string"
},
"name": {
"$ref": "#/components/schemas/ToolName"
}
},
"type": "object"
},
"id": {
"$ref": "#/components/schemas/ToolCallId"
},
"type": {
"enum": [
"function",
"web",
"x_search",
"code_execution",
"image_generation"
],
"type": "string"
}
},
"required": [
"id",
"type"
],
"type": "object"
},
"ToolCallDelta": {
"description": "Incremental tool call data during streaming",
"properties": {
"function": {
"properties": {
"arguments": {
"description": "Partial JSON string",
"type": "string"
},
"name": {
"$ref": "#/components/schemas/ToolName"
}
},
"type": "object"
},
"id": {
"$ref": "#/components/schemas/ToolCallId"
},
"index": {
"format": "uint32",
"minimum": 0,
"type": "integer"
},
"type": {
"type": "string"
}
},
"type": "object"
},
"ToolCallId": {
"description": "Unique identifier for a tool call. Treated as an opaque string and must be preserved exactly.",
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"ToolChoice": {
"properties": {
"function": {
"$ref": "#/components/schemas/ToolName"
},
"type": {
"enum": [
"auto",
"required",
"none"
],
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"ToolHookConfig": {
"properties": {
"allow_mutation": {
"type": "boolean"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"endpoint_url": {
"format": "uri",
"type": "string"
},
"fail_behavior": {
"enum": [
"fail_closed",
"fail_open"
],
"type": "string"
},
"hook_type": {
"enum": [
"pre_tool_use",
"post_tool_use",
"tool_execute"
],
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"project_id": {
"format": "uuid",
"type": "string"
},
"timeout_ms": {
"format": "int32",
"type": "integer"
},
"tools_allowlist": {
"items": {
"type": "string"
},
"type": "array"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"ToolHookConfigInput": {
"properties": {
"allow_mutation": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"endpoint_url": {
"format": "uri",
"type": "string"
},
"fail_behavior": {
"enum": [
"fail_closed",
"fail_open"
],
"type": "string"
},
"hook_type": {
"enum": [
"pre_tool_use",
"post_tool_use",
"tool_execute"
],
"type": "string"
},
"timeout_ms": {
"format": "int32",
"type": "integer"
},
"tools_allowlist": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"hook_type",
"endpoint_url"
],
"type": "object"
},
"ToolHookConfigUpdate": {
"properties": {
"allow_mutation": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"endpoint_url": {
"format": "uri",
"type": "string"
},
"fail_behavior": {
"enum": [
"fail_closed",
"fail_open"
],
"type": "string"
},
"rotate_secret": {
"type": "boolean"
},
"timeout_ms": {
"format": "int32",
"type": "integer"
},
"tools_allowlist": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"ToolHookEvent": {
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"error": {
"type": "string"
},
"hook_config_id": {
"format": "uuid",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"latency_ms": {
"format": "int32",
"type": "integer"
},
"request_id": {
"type": "string"
},
"response_body": {
"type": "string"
},
"response_status": {
"format": "int32",
"type": "integer"
},
"status": {
"enum": [
"success",
"blocked",
"timeout",
"error"
],
"type": "string"
},
"tool_call_id": {
"type": "string"
}
},
"type": "object"
},
"ToolHookTestResult": {
"properties": {
"error": {
"type": "string"
},
"latency_ms": {
"format": "int32",
"type": "integer"
},
"response_body": {
"type": "string"
},
"response_status": {
"format": "int32",
"type": "integer"
},
"status": {
"enum": [
"success",
"blocked",
"timeout",
"error"
],
"type": "string"
}
},
"type": "object"
},
"ToolName": {
"description": "Tool identifier. For tools.v0 client tools, use dot-separated lowercase segments (e.g. fs.search).",
"maxLength": 128,
"minLength": 1,
"pattern": "^[a-z][a-z0-9_]*(\\\\.[a-z][a-z0-9_]*)*$",
"type": "string"
},
"Usage": {
"description": "Token usage statistics. All fields default to 0 if not present.",
"properties": {
"input_tokens": {
"default": 0,
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"output_tokens": {
"default": 0,
"format": "uint64",
"minimum": 0,
"type": "integer"
},
"total_tokens": {
"default": 0,
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
"type": "object"
},
"User": {
"properties": {
"email": {
"format": "email",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"project_id": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"WebhookConfig": {
"properties": {
"created_at": {
"format": "date-time",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"endpoint_url": {
"format": "uri",
"type": "string"
},
"events": {
"items": {
"enum": [
"customer.created",
"customer.updated",
"customer.deleted",
"usage.threshold_exceeded",
"request.completed",
"billing.subscription_changed"
],
"type": "string"
},
"type": "array"
},
"id": {
"format": "uuid",
"type": "string"
},
"project_id": {
"format": "uuid",
"type": "string"
},
"signing_secret": {
"type": "string"
},
"updated_at": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"WebhookConfigInput": {
"properties": {
"enabled": {
"type": "boolean"
},
"endpoint_url": {
"format": "uri",
"type": "string"
},
"events": {
"items": {
"enum": [
"customer.created",
"customer.updated",
"customer.deleted",
"usage.threshold_exceeded",
"request.completed",
"billing.subscription_changed"
],
"type": "string"
},
"type": "array"
}
},
"required": [
"endpoint_url",
"events"
],
"type": "object"
},
"WebhookConfigUpdate": {
"properties": {
"enabled": {
"type": "boolean"
},
"endpoint_url": {
"format": "uri",
"type": "string"
},
"events": {
"items": {
"enum": [
"customer.created",
"customer.updated",
"customer.deleted",
"usage.threshold_exceeded",
"request.completed",
"billing.subscription_changed"
],
"type": "string"
},
"type": "array"
},
"rotate_secret": {
"type": "boolean"
}
},
"required": [
"endpoint_url",
"events"
],
"type": "object"
},
"WebhookTestResult": {
"properties": {
"error": {
"type": "string"
},
"latency_ms": {
"format": "int32",
"type": "integer"
},
"response_body": {
"type": "string"
},
"response_status": {
"format": "int32",
"type": "integer"
},
"status": {
"enum": [
"delivered",
"failed"
],
"type": "string"
}
},
"type": "object"
},
"WorkflowSpec": {
"additionalProperties": true,
"description": "A `workflow` spec. The canonical JSON Schema is available at `/schemas/workflow.schema.json`.",
"type": "object"
},
"WorkflowIssue": {
"description": "A lint or compile issue for a workflow spec.",
"properties": {
"code": {
"description": "Issue code",
"type": "string"
},
"path": {
"description": "JSON path to the issue location (e.g., $.nodes[0].id)",
"type": "string"
},
"message": {
"description": "Human-readable issue description",
"type": "string"
}
},
"required": [
"code",
"path",
"message"
],
"type": "object"
},
"RunsToolResultsRequest": {
"description": "Request to submit tool execution results for a waiting run.",
"properties": {
"node_id": {
"$ref": "#/components/schemas/NodeId"
},
"step": {
"description": "Execution step from pending-tools",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
},
"results": {
"description": "Tool execution results",
"items": {
"$ref": "#/components/schemas/RunToolResultV0"
},
"type": "array"
}
},
"required": [
"node_id",
"step",
"request_id",
"results"
],
"type": "object"
},
"RunsToolResultsResponse": {
"description": "Response after submitting tool results.",
"properties": {
"accepted": {
"description": "Number of tool results accepted",
"format": "int64",
"minimum": 0,
"type": "integer"
},
"status": {
"$ref": "#/components/schemas/RunStatusV0"
}
},
"required": [
"accepted",
"status"
],
"type": "object"
},
"WorkflowsCompileResponse": {
"description": "Response from compiling a workflow spec.",
"properties": {
"plan_json": {
"description": "Canonical compiled plan JSON",
"type": "object"
},
"plan_hash": {
"description": "Hash of the compiled plan",
"type": "string"
}
},
"required": [
"plan_json",
"plan_hash"
],
"type": "object"
},
"WorkflowsLintResponse": {
"description": "Response from linting a workflow spec.",
"properties": {
"kind": {
"description": "Workflow kind (e.g., workflow)",
"type": "string"
},
"lint_issues": {
"description": "Lint issues found in the spec",
"items": {
"$ref": "#/components/schemas/WorkflowIssue"
},
"type": "array"
},
"compile_issues": {
"description": "Compile issues (when compile is enabled)",
"items": {
"$ref": "#/components/schemas/WorkflowIssue"
},
"type": "array"
},
"compile_error": {
"description": "Non-validation compile failure message",
"type": "string"
},
"plan_json": {
"description": "Compiled plan JSON (when compile succeeds)",
"type": "object"
},
"plan_hash": {
"description": "Plan hash (when compile succeeds)",
"type": "string"
}
},
"type": "object"
},
"MessageSendRequest": {
"type": "object",
"properties": {
"to": {
"type": "string"
},
"subject": {
"type": "string"
},
"body": {
"type": "object",
"additionalProperties": true
},
"thread_id": {
"type": "string",
"format": "uuid"
},
"from": {
"type": "string"
}
},
"required": [
"to",
"subject",
"body"
]
},
"MessageResponse": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"subject": {
"type": "string"
},
"body": {
"type": "object",
"additionalProperties": true
},
"thread_id": {
"type": "string",
"format": "uuid"
},
"read": {
"type": "boolean"
},
"read_at": {
"type": "string"
},
"created_at": {
"type": "string"
}
},
"required": [
"id",
"project_id",
"from",
"to",
"subject",
"body",
"thread_id",
"read",
"created_at"
]
},
"MessageListResponse": {
"type": "object",
"properties": {
"messages": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MessageResponse"
}
},
"next_cursor": {
"type": "string"
}
},
"required": [
"messages"
]
}
},
"securitySchemes": {
"apiKeyAuth": {
"in": "header",
"name": "X-ModelRelay-Api-Key",
"type": "apiKey"
},
"bearerAuth": {
"bearerFormat": "JWT",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"description": "Control-plane and inference endpoints for ModelRelay projects, tiers, customers, billing, and LLM proxying.",
"title": "ModelRelay API",
"version": "0.7.0"
},
"openapi": "3.0.3",
"paths": {
"/auth/customer-token": {
"post": {
"description": "Used by trusted backends to mint short-lived customer-scoped bearer tokens\nfor data-plane access (/responses, /runs). Requires a secret API key (mr_sk_*).\nThe customer must already exist; use /customers endpoints to create customers first.\n",
"operationId": "mintCustomerToken",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"customer_external_id": {
"description": "External customer identifier (provide exactly one of customer_id or customer_external_id)",
"type": "string"
},
"customer_id": {
"description": "Internal customer UUID (provide exactly one of customer_id or customer_external_id)",
"format": "uuid",
"type": "string"
},
"ttl_seconds": {
"description": "Requested token TTL in seconds (server may cap this)",
"format": "uint32",
"minimum": 1,
"type": "integer"
},
"tier_code": {
"description": "Tier code for the customer. Required when creating a subscription for new customers. Customers with an existing subscription can omit this field.",
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTokenResponse"
}
}
},
"description": "Customer token issued"
},
"400": {
"description": "Invalid request (missing or invalid customer selector)"
},
"401": {
"description": "Invalid or missing secret key"
},
"404": {
"description": "Customer not found"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Mint a customer-scoped bearer token"
}
},
"/auth/login": {
"post": {
"operationId": "login",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"email": {
"format": "email",
"type": "string"
},
"password": {
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthResponse"
}
}
},
"description": "Tokens issued"
}
},
"summary": "Exchange credentials for tokens"
}
},
"/auth/logout": {
"post": {
"operationId": "logout",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"refresh_token": {
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Session revoked"
}
},
"summary": "Revoke a refresh token"
}
},
"/auth/me": {
"get": {
"operationId": "getAuthenticatedUser",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
},
"type": "object"
}
}
},
"description": "Current user"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Fetch the authenticated user profile"
}
},
"/auth/refresh": {
"post": {
"operationId": "refreshToken",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"refresh_token": {
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthTokens"
}
}
},
"description": "Tokens refreshed"
}
},
"summary": "Refresh an access token"
}
},
"/auth/register": {
"post": {
"operationId": "registerOwner",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"email": {
"format": "email",
"type": "string"
},
"password": {
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthResponse"
}
}
},
"description": "User created"
}
},
"summary": "Register a new owner account"
}
},
"/account/billing/auto-topup": {
"get": {
"operationId": "getAccountAutoTopup",
"responses": {
"200": {
"description": "Auto top-up configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutoTopupConfigResponse"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"500": {
"description": "Failed to get auto top-up configuration"
},
"503": {
"description": "Auto top-up service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get auto top-up configuration for the authenticated account"
},
"put": {
"operationId": "updateAccountAutoTopup",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutoTopupConfigRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Auto top-up configuration updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutoTopupConfigResponse"
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"503": {
"description": "Auto top-up service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Update auto top-up configuration for the authenticated account"
},
"delete": {
"operationId": "disableAccountAutoTopup",
"responses": {
"204": {
"description": "Auto top-up disabled"
},
"401": {
"description": "Unauthorized"
},
"500": {
"description": "Failed to disable auto top-up"
},
"503": {
"description": "Auto top-up service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Disable auto top-up for the authenticated account"
}
},
"/account/billing/auto-topup/setup": {
"post": {
"operationId": "createAccountAutoTopupSetup",
"responses": {
"200": {
"description": "Setup intent created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutoTopupSetupResponse"
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"503": {
"description": "Auto top-up service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a setup intent for auto top-up payment methods"
}
},
"/account/billing/auto-topup/confirm": {
"post": {
"operationId": "confirmAccountAutoTopupSetup",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutoTopupConfirmRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Auto top-up payment method stored",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AutoTopupConfigResponse"
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"503": {
"description": "Auto top-up service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Confirm auto top-up setup intent"
}
},
"/customers": {
"get": {
"operationId": "listCustomers",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"customers": {
"items": {
"$ref": "#/components/schemas/CustomerWithSubscription"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "Customer list"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "List customers"
},
"post": {
"operationId": "createProjectCustomer",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
},
"type": "object"
}
}
},
"description": "Customer created"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Create a customer"
},
"put": {
"operationId": "upsertCustomer",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerCreate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
},
"type": "object"
}
}
},
"description": "Customer updated"
},
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
},
"type": "object"
}
}
},
"description": "Customer created"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Upsert a customer by external_id"
}
},
"/customers/me": {
"get": {
"description": "Returns the current customer associated with the provided customer-scoped bearer token.\nIncludes the customer's subscription and tier when available.\n",
"operationId": "getCustomerMe",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeResponse"
}
}
},
"description": "Customer details"
},
"401": {
"description": "Unauthorized"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get the authenticated customer"
}
},
"/customers/me/balance": {
"get": {
"operationId": "getCustomerMeBalance",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerBalanceResponse"
}
}
},
"description": "PAYGO balance"
},
"400": {
"description": "Subscription is not PAYGO"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer or subscription not found"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get the authenticated customer's PAYGO balance"
}
},
"/customers/me/balance/history": {
"get": {
"operationId": "getCustomerMeBalanceHistory",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"format": "int32",
"maximum": 200,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"format": "int32",
"minimum": 0,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerLedgerResponse"
}
}
},
"description": "Ledger entries"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer not found"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get the authenticated customer's PAYGO ledger history"
}
},
"/customers/me/change-tier": {
"post": {
"description": "Allows customers to upgrade or downgrade their subscription tier. Supports paid-to-paid (with proration), free-to-paid (requires payment method on file), paid-to-free (cancels at period end), and free-to-free transitions.",
"operationId": "changeCustomerMeTier",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeTierRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeSubscriptionResponse"
}
}
},
"description": "Tier changed successfully"
},
"400": {
"description": "Invalid request (missing tier_code, same tier, or PAYGO subscription)"
},
"401": {
"description": "Unauthorized"
},
"402": {
"description": "No payment method on file (required for free-to-paid upgrade)"
},
"404": {
"description": "Customer or tier not found"
},
"409": {
"description": "Billing provider mismatch"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Change the authenticated customer's subscription tier"
}
},
"/customers/me/checkout": {
"post": {
"description": "Creates a Stripe checkout session using the customer-first flow. A Stripe Customer is created with the verified OAuth email before checkout, preventing email spoofing. The email field in the Stripe checkout will be locked to the authenticated user's email.",
"operationId": "createCustomerMeCheckout",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeCheckoutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutSessionResponse"
}
}
},
"description": "Checkout session created successfully"
},
"400": {
"description": "Invalid request (missing or invalid tier_code, success_url, or cancel_url)"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer or tier not found"
},
"409": {
"description": "Tier has no billing pricing configured"
},
"503": {
"description": "Billing not configured"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a checkout session for the authenticated customer"
}
},
"/customers/me/subscription": {
"get": {
"description": "Returns customer-visible subscription details for the authenticated customer bearer token.\nIncludes tier name and subscription price; does not include developer-private usage cost accounting.\n",
"operationId": "getCustomerMeSubscription",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeSubscriptionResponse"
}
}
},
"description": "Subscription details"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer or tier not found"
},
"500": {
"description": "Internal server error"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get the authenticated customer's subscription"
}
},
"/customers/me/topup": {
"post": {
"operationId": "createCustomerMeTopup",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTopupRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTopupResponse"
}
}
},
"description": "Checkout session created"
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer not found"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a PAYGO top-up checkout session for the authenticated customer"
}
},
"/customers/me/usage": {
"get": {
"description": "Returns customer-visible usage metrics for the current billing window.\nIncludes request/token counts and (for paid tiers) remaining subscription credits.\nDoes not include any developer-private budgets (e.g., internal tier spend caps).\n",
"operationId": "getCustomerMeUsage",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeUsageResponse"
}
}
},
"description": "Usage summary"
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer not found"
},
"500": {
"description": "Failed to calculate usage"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get the authenticated customer's usage"
}
},
"/customers/by-external-id/{external_id}": {
"get": {
"description": "Returns a customer by their external_id. Use this when you have the customer's external identifier (e.g., GitHub ID) but not their internal UUID.",
"operationId": "getCustomerByExternalId",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
},
"type": "object"
}
}
},
"description": "Customer"
},
"400": {
"description": "external_id required"
},
"404": {
"description": "Customer not found"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Get a customer by external_id"
},
"parameters": [
{
"description": "The customer's external identifier (e.g., GitHub ID)",
"in": "path",
"name": "external_id",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/customers/{customer_id}": {
"delete": {
"operationId": "deleteProjectCustomer",
"responses": {
"204": {
"description": "Customer deleted"
},
"404": {
"description": "Customer not found"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Delete a customer"
},
"get": {
"operationId": "getCustomer",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
},
"type": "object"
}
}
},
"description": "Customer"
},
"404": {
"description": "Customer not found"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Get a customer"
},
"parameters": [
{
"in": "path",
"name": "customer_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/customers/{customer_id}/balance": {
"get": {
"operationId": "getCustomerBalance",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerBalanceResponse"
}
}
},
"description": "PAYGO balance"
},
"400": {
"description": "Subscription is not PAYGO"
},
"404": {
"description": "Customer or subscription not found"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Get a customer's PAYGO balance"
},
"parameters": [
{
"in": "path",
"name": "customer_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/customers/{customer_id}/balance/history": {
"get": {
"operationId": "getCustomerBalanceHistory",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"format": "int32",
"maximum": 200,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"format": "int32",
"minimum": 0,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerLedgerResponse"
}
}
},
"description": "Ledger entries"
},
"404": {
"description": "Customer not found"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Get a customer's PAYGO ledger history"
},
"parameters": [
{
"in": "path",
"name": "customer_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/customers/{customer_id}/subscribe": {
"parameters": [
{
"in": "path",
"name": "customer_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"post": {
"operationId": "subscribeCustomer",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"cancel_url": {
"format": "uri",
"type": "string"
},
"success_url": {
"format": "uri",
"type": "string"
},
"tier_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"tier_id",
"success_url",
"cancel_url"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutSessionResponse"
}
}
},
"description": "Checkout session created"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Create a customer subscription checkout session"
}
},
"/customers/{customer_id}/subscription": {
"delete": {
"operationId": "cancelCustomerSubscription",
"responses": {
"204": {
"description": "Subscription canceled"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Cancel a customer's subscription"
},
"get": {
"operationId": "getCustomerSubscription",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"subscription": {
"$ref": "#/components/schemas/Subscription"
}
},
"type": "object"
}
}
},
"description": "Subscription details"
},
"404": {
"description": "Subscription not found"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Get a customer's subscription"
},
"parameters": [
{
"in": "path",
"name": "customer_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/customers/{customer_id}/topup": {
"parameters": [
{
"in": "path",
"name": "customer_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"post": {
"operationId": "createCustomerTopup",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTopupRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTopupResponse"
}
}
},
"description": "Checkout session created"
},
"400": {
"description": "Invalid request"
},
"404": {
"description": "Customer not found"
},
"503": {
"description": "Service unavailable"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Create a PAYGO top-up checkout session for a customer"
}
},
"/images/generate": {
"post": {
"description": "Generate images using AI models. Returns URLs by default (requires storage configuration) or base64-encoded data when response_format is 'b64_json'.",
"operationId": "generateImage",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageResponse"
}
}
},
"description": "Generated images"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Generate images from a text prompt"
}
},
"/images/{image_id}": {
"get": {
"description": "Retrieve information about a specific image, including its pinned status and URL.",
"operationId": "getImage",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImagePinResponse"
}
}
},
"description": "Image details"
},
"404": {
"description": "Image not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Get image details"
},
"parameters": [
{
"description": "Image ID",
"in": "path",
"name": "image_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/images/{image_id}/pin": {
"delete": {
"description": "Unpin an image, setting it to expire after the default ephemeral period (7 days).",
"operationId": "unpinImage",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImagePinResponse"
}
}
},
"description": "Image unpinned successfully"
},
"404": {
"description": "Image not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Unpin an image"
},
"parameters": [
{
"description": "Image ID",
"in": "path",
"name": "image_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"post": {
"description": "Pin an image to prevent it from expiring. Pinned images remain accessible permanently (subject to tier limits).",
"operationId": "pinImage",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImagePinResponse"
}
}
},
"description": "Image pinned successfully"
},
"403": {
"description": "Quota exceeded"
},
"404": {
"description": "Image not found"
},
"410": {
"description": "Image has expired"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Pin an image"
}
},
"/models": {
"get": {
"description": "Returns all active models with rich metadata for building model selectors.",
"operationId": "listModels",
"parameters": [
{
"description": "Filter results to a specific provider",
"in": "query",
"name": "provider",
"required": false,
"schema": {
"$ref": "#/components/schemas/ProviderId"
}
},
{
"description": "Filter results to models that support a capability",
"in": "query",
"name": "capability",
"required": false,
"schema": {
"$ref": "#/components/schemas/ModelCapability"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelsResponse"
}
}
},
"description": "Models list"
}
},
"summary": "List active models"
}
},
"/projects": {
"get": {
"operationId": "listProjects",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"projects": {
"items": {
"$ref": "#/components/schemas/Project"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "Project list"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List projects for the authenticated owner"
},
"post": {
"operationId": "createProject",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"description": {
"type": "string"
},
"markup_percentage": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"name": {
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"project": {
"$ref": "#/components/schemas/Project"
}
},
"type": "object"
}
}
},
"description": "Project created"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a project"
}
},
"/projects/{id}": {
"delete": {
"operationId": "deleteProject",
"responses": {
"204": {
"description": "Project deleted"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Delete a project"
},
"get": {
"operationId": "getProject",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"project": {
"$ref": "#/components/schemas/Project"
}
},
"type": "object"
}
}
},
"description": "Project found"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get a project"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"put": {
"operationId": "updateProject",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"billing_mode": {
"$ref": "#/components/schemas/BillingMode"
},
"description": {
"type": "string"
},
"markup_percentage": {
"maximum": 100,
"minimum": 0,
"type": "number"
},
"name": {
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"project": {
"$ref": "#/components/schemas/Project"
}
},
"type": "object"
}
}
},
"description": "Project updated"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Update a project"
}
},
"/projects/{id}/customers": {
"get": {
"operationId": "listProjectCustomers",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"customers": {
"items": {
"$ref": "#/components/schemas/CustomerWithSubscription"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "Customer list"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List customers for a project"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"post": {
"operationId": "createCustomer",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
},
"type": "object"
}
}
},
"description": "Customer created"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a customer"
}
},
"/projects/{id}/customers/{customer_id}": {
"delete": {
"operationId": "deleteCustomer",
"responses": {
"204": {
"description": "Customer deleted"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Delete a customer"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"in": "path",
"name": "customer_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/projects/{id}/tiers": {
"get": {
"operationId": "listProjectTiers",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"tiers": {
"items": {
"$ref": "#/components/schemas/Tier"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "Tier list"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List tiers for a project"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"post": {
"operationId": "createTier",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TierCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"tier": {
"$ref": "#/components/schemas/Tier"
}
},
"type": "object"
}
}
},
"description": "Tier created"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a tier"
}
},
"/projects/{id}/tiers/{tier_id}": {
"delete": {
"operationId": "deleteTier",
"responses": {
"204": {
"description": "Tier deleted"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Delete a tier"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"in": "path",
"name": "tier_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"put": {
"operationId": "updateTier",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TierUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Tier updated"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Update a tier"
}
},
"/projects/{id}/tool-hooks": {
"get": {
"operationId": "listProjectToolHooks",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"hooks": {
"items": {
"$ref": "#/components/schemas/ToolHookConfig"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "Tool hook list"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List project tool hooks"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"post": {
"operationId": "createProjectToolHook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolHookConfigInput"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"hook": {
"$ref": "#/components/schemas/ToolHookConfig"
},
"signing_secret": {
"type": "string"
}
},
"type": "object"
}
}
},
"description": "Tool hook created"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a project tool hook"
}
},
"/projects/{id}/tool-hooks/{hook_id}": {
"delete": {
"operationId": "deleteProjectToolHook",
"responses": {
"204": {
"description": "Tool hook deleted"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Delete a project tool hook"
},
"get": {
"operationId": "getProjectToolHook",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"hook": {
"$ref": "#/components/schemas/ToolHookConfig"
}
},
"type": "object"
}
}
},
"description": "Tool hook details"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get a project tool hook"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/ToolHookID"
}
],
"put": {
"operationId": "updateProjectToolHook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolHookConfigUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"hook": {
"$ref": "#/components/schemas/ToolHookConfig"
},
"signing_secret": {
"type": "string"
}
},
"type": "object"
}
}
},
"description": "Tool hook updated"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Update a project tool hook"
}
},
"/projects/{id}/tool-hooks/{hook_id}/events": {
"get": {
"operationId": "listProjectToolHookEvents",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"events": {
"items": {
"$ref": "#/components/schemas/ToolHookEvent"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "Tool hook events"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List tool hook delivery events"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/ToolHookID"
}
]
},
"/projects/{id}/tool-hooks/{hook_id}/test": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/ToolHookID"
}
],
"post": {
"operationId": "testProjectToolHook",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolHookTestResult"
}
}
},
"description": "Tool hook test result"
},
"502": {
"description": "Tool hook test failed"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Test a tool hook"
}
},
"/projects/{id}/agents": {
"get": {
"operationId": "listProjectAgents",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentListResponse"
}
}
},
"description": "Agent list"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List project agents"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"post": {
"operationId": "createProjectAgent",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentResponse"
}
}
},
"description": "Agent created"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a project agent"
}
},
"/projects/{id}/agents/{slug}": {
"delete": {
"operationId": "deleteProjectAgent",
"responses": {
"204": {
"description": "Agent deleted"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Delete a project agent"
},
"get": {
"operationId": "getProjectAgent",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentResponse"
}
}
},
"description": "Agent details"
},
"404": {
"description": "Agent not found"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get a project agent"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"in": "path",
"name": "slug",
"required": true,
"schema": {
"type": "string"
}
}
],
"patch": {
"operationId": "updateProjectAgent",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentResponse"
}
}
},
"description": "Agent updated"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Update a project agent"
}
},
"/projects/{id}/agents/{slug}/run": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"in": "path",
"name": "slug",
"required": true,
"schema": {
"type": "string"
}
}
],
"post": {
"operationId": "runAgent",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentRunRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentRunResponse"
}
},
"text/event-stream": {
"schema": {
"type": "string"
}
},
"application/x-ndjson": {
"schema": {
"type": "string"
}
}
},
"description": "Agent run result"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Run an agent"
}
},
"/projects/{id}/agents/{slug}/test": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"in": "path",
"name": "slug",
"required": true,
"schema": {
"type": "string"
}
}
],
"post": {
"operationId": "testAgent",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentTestRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentRunResponse"
}
}
},
"description": "Agent test result"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Test an agent"
}
},
"/projects/{id}/agents/{slug}/replay": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"in": "path",
"name": "slug",
"required": true,
"schema": {
"type": "string"
}
}
],
"post": {
"operationId": "replayAgent",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentTestRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AgentRunResponse"
}
}
},
"description": "Agent replay result"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Replay an agent"
}
},
"/projects/{id}/webhooks": {
"get": {
"operationId": "listProjectWebhooks",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"webhooks": {
"items": {
"$ref": "#/components/schemas/WebhookConfig"
},
"type": "array"
}
},
"type": "object"
}
}
},
"description": "Webhook list"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List project webhooks"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"post": {
"operationId": "createProjectWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookConfigInput"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"webhook": {
"$ref": "#/components/schemas/WebhookConfig"
}
},
"type": "object"
}
}
},
"description": "Webhook created"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Create a project webhook"
}
},
"/projects/{id}/webhooks/{webhook_id}": {
"delete": {
"operationId": "deleteProjectWebhook",
"responses": {
"204": {
"description": "Webhook deleted"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Delete a project webhook"
},
"get": {
"operationId": "getProjectWebhook",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"webhook": {
"$ref": "#/components/schemas/WebhookConfig"
}
},
"type": "object"
}
}
},
"description": "Webhook details"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Get a project webhook"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/WebhookID"
}
],
"put": {
"operationId": "updateProjectWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookConfigUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"webhook": {
"$ref": "#/components/schemas/WebhookConfig"
}
},
"type": "object"
}
}
},
"description": "Webhook updated"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Update a project webhook"
}
},
"/projects/{id}/webhooks/{webhook_id}/events": {
"get": {
"operationId": "listProjectWebhookEvents",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "event_type",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"events": {
"items": {
"$ref": "#/components/schemas/OutboundWebhookEvent"
},
"type": "array"
},
"next_cursor": {
"type": "string"
}
},
"type": "object"
}
}
},
"description": "Webhook events"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "List webhook delivery events"
},
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/WebhookID"
}
]
},
"/projects/{id}/webhooks/{webhook_id}/test": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/WebhookID"
}
],
"post": {
"operationId": "testProjectWebhook",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"event_type": {
"type": "string"
}
},
"type": "object"
}
}
},
"required": false
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookTestResult"
}
}
},
"description": "Webhook test result"
},
"502": {
"description": "Webhook test failed"
}
},
"security": [
{
"bearerAuth": []
}
],
"summary": "Test a webhook"
}
},
"/responses": {
"post": {
"description": "Creates a model response. Auth accepts secret API keys or bearer tokens. Bearer tokens may be owner session tokens (dashboard/server) or customer tokens; publishable keys are not allowed. Persistent tool state requires a state handle created via /state-handles.",
"operationId": "createResponse",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesResponse"
}
}
},
"description": "Response"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Create a response via the provider-agnostic API"
}
},
"/state-handles": {
"get": {
"description": "List state handles for the current project or customer.",
"operationId": "listStateHandles",
"parameters": [
{
"in": "query",
"name": "limit",
"schema": {
"format": "int32",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"schema": {
"format": "int32",
"minimum": 0,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StateHandleListResponse"
}
}
},
"description": "State handles"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "List state handles"
},
"post": {
"description": "Create a state handle for persistent /responses tool state.",
"operationId": "createStateHandle",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StateHandleCreateRequest"
}
}
},
"required": false
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StateHandleResponse"
}
}
},
"description": "State handle"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Create a state handle"
}
},
"/state-handles/{state_id}": {
"delete": {
"operationId": "deleteStateHandle",
"parameters": [
{
"in": "path",
"name": "state_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "State handle deleted"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Delete a state handle"
}
},
"/responses:batch": {
"post": {
"operationId": "createResponsesBatch",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesBatchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesBatchResponse"
}
}
},
"description": "Batch response results"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Create multiple responses concurrently (batch)"
}
},
"/plugins/compile": {
"post": {
"operationId": "compilePlugin",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PluginsCompileRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PluginsCompileResponse"
}
}
},
"description": "Compiled plugin"
},
"400": {
"description": "Invalid source format"
},
"404": {
"description": "Plugin not found"
},
"422": {
"description": "Plugin parse or workflow generation failed"
},
"429": {
"description": "GitHub rate limited"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Compile a Claude Code plugin to workflow"
}
},
"/runs": {
"post": {
"description": "Starts a run for a `workflow` spec and returns a `run_id`. Auth matches `/responses` (API key or frontend bearer token). Session owner tokens from `/auth/login` are not accepted. Provide `session_id` to link the run to a session; when linked, assistant messages are appended to the session on completion. The workflow spec must include resolved models for all llm.responses/route.switch nodes; /runs does not resolve tier defaults.",
"operationId": "createRun",
"parameters": [
{
"description": "When true, override all llm.responses and route.switch nodes to stream (emit node_output_delta events). When false or omitted, uses the workflow spec defaults.",
"in": "query",
"name": "stream",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsCreateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsCreateResponse"
}
}
},
"description": "Run created (or idempotent replay)"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Start a workflow run"
}
},
"/runs/{run_id}": {
"get": {
"description": "Returns a derived snapshot state for the run (folded from event history + artifacts), including outputs and an aggregated cost summary when available.",
"operationId": "getRun",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsGetResponse"
}
}
},
"description": "Run snapshot"
},
"404": {
"description": "Run not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Get a derived run snapshot"
},
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Comma-separated list of additional fields to include. Supported values: steps, tool_calls.",
"in": "query",
"name": "include",
"required": false,
"schema": {
"type": "string"
}
}
]
},
"/runs/{run_id}/events": {
"get": {
"description": "Streams an append-only, totally ordered history for the run. The wire format is negotiated via `Accept`: NDJSON (`application/x-ndjson`) or Server-Sent Events (`text/event-stream`). Each line/event is a `run_event` envelope; see `/schemas/run_event.schema.json` for the canonical schema.",
"operationId": "streamRunEvents",
"responses": {
"200": {
"content": {
"application/x-ndjson": {
"example": "{\"envelope_version\":\"v2\",\"seq\":1,\"type\":\"run_compiled\",...}\n{\"envelope_version\":\"v2\",\"seq\":2,\"type\":\"run_started\",...}\n",
"schema": {
"type": "string"
}
},
"text/event-stream": {
"example": "event: run_started\nid: 2\ndata: {\"envelope_version\":\"v2\",\"seq\":2,\"type\":\"run_started\",...}\n",
"schema": {
"type": "string"
}
}
},
"description": "Event stream (NDJSON or SSE)"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Stream run events (append-only)"
},
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Returns events where `seq > after_seq`.",
"in": "query",
"name": "after_seq",
"required": false,
"schema": {
"format": "uint64",
"minimum": 0,
"type": "integer"
}
},
{
"description": "When false, returns currently available events then closes.",
"in": "query",
"name": "wait",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "When true, inline node_output and run_completed payloads when they are <= 1MB.",
"in": "query",
"name": "include_output",
"required": false,
"schema": {
"type": "boolean"
}
},
{
"description": "Maximum number of events to send before closing.",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"format": "uint32",
"maximum": 10000,
"minimum": 1,
"type": "integer"
}
}
]
},
"/runs/{run_id}/steps": {
"get": {
"description": "Returns step-level execution details for agentic loops, including per-step LLM calls and tool I/O when available.",
"operationId": "listRunSteps",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunStepsResponse"
}
}
},
"description": "Run steps"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "List run steps"
},
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/runs/{run_id}/tasks": {
"get": {
"description": "Returns the run-scoped task list written by the tasks.write tool.",
"operationId": "getRunTasks",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunTasksResponse"
}
}
},
"description": "Run tasks"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Get run tasks"
},
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/runs/{run_id}/steps/{step}/tool-calls/{tool_id}": {
"get": {
"description": "Returns a specific tool call detail for a given run step.",
"operationId": "getRunStepToolCall",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunToolCallDetail"
}
}
},
"description": "Tool call detail"
},
"404": {
"description": "Tool call not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Get run tool call detail"
},
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "step",
"required": true,
"schema": {
"minimum": 0,
"type": "integer"
}
},
{
"in": "path",
"name": "tool_id",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"/schemas/run_event.schema.json": {
"get": {
"description": "Returns the canonical JSON Schema (draft-07) for `run_event` (workflow run history events).",
"operationId": "getRunEventV0Schema",
"responses": {
"200": {
"content": {
"application/schema+json": {
"schema": {
"type": "object"
}
}
},
"description": "Schema document"
}
},
"summary": "Get JSON Schema for run_event"
}
},
"/sessions": {
"get": {
"description": "Returns a paginated list of sessions for the project.",
"operationId": "listSessions",
"parameters": [
{
"description": "Maximum number of sessions to return",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"format": "int32",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Number of sessions to skip",
"in": "query",
"name": "offset",
"required": false,
"schema": {
"format": "int32",
"minimum": 0,
"type": "integer"
}
},
{
"description": "Filter sessions by customer ID",
"in": "query",
"name": "customer_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionListResponse"
}
}
},
"description": "Session list"
},
"401": {
"description": "API key required"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "List sessions"
},
"post": {
"description": "Creates a new session for multi-turn conversation management. Sessions persist message history on the server for cross-device continuity.",
"operationId": "createSession",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponse"
}
}
},
"description": "Session created"
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "API key required"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Create a new session"
}
},
"/sessions/{session_id}": {
"delete": {
"description": "Deletes a session and all its messages. Requires a secret API key (mr_sk_*).",
"operationId": "deleteSession",
"responses": {
"204": {
"description": "Session deleted"
},
"403": {
"description": "Secret key required for deletion"
},
"404": {
"description": "Session not found"
}
},
"security": [
{
"apiKeyAuth": []
}
],
"summary": "Delete a session"
},
"get": {
"description": "Returns a session including its full message history.",
"operationId": "getSession",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionWithMessagesResponse"
}
}
},
"description": "Session with messages"
},
"404": {
"description": "Session not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Get session with messages"
},
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"patch": {
"description": "Updates session metadata. Keys with null values are removed.",
"operationId": "updateSession",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponse"
}
}
},
"description": "Session updated"
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "API key required"
},
"404": {
"description": "Session not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Update session metadata"
}
},
"/sessions/{session_id}/clear": {
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"post": {
"description": "Deletes all messages in the session and returns the updated session.",
"operationId": "clearSession",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponse"
}
}
},
"description": "Session cleared"
},
"401": {
"description": "API key required"
},
"404": {
"description": "Session not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Clear session messages"
}
},
"/sessions/{session_id}/messages": {
"parameters": [
{
"in": "path",
"name": "session_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"post": {
"description": "Appends a message to an existing session.",
"operationId": "addSessionMessage",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionMessageCreateRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionMessageResponse"
}
}
},
"description": "Message appended"
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "API key required"
},
"404": {
"description": "Session not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Append a session message"
}
},
"/schemas/workflow.schema.json": {
"get": {
"description": "Returns the canonical JSON Schema (draft-07) for `workflow`.",
"operationId": "getWorkflowSchema",
"responses": {
"200": {
"description": "Schema document",
"content": {
"application/schema+json": {
"schema": {
"type": "object"
}
}
}
}
},
"summary": "Get JSON Schema for workflow"
}
},
"/runs/{run_id}/pending-tools": {
"get": {
"description": "Returns pending tool calls for runs using client-side tool execution mode. When a node emits a node_waiting event, use this endpoint to retrieve the tool calls that need execution.",
"operationId": "getRunPendingTools",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsPendingToolsResponse"
}
}
},
"description": "Pending tool calls"
},
"404": {
"description": "Run not found"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Get pending tool calls"
},
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/runs/{run_id}/tool-results": {
"post": {
"description": "Submits tool execution results to resume a waiting run. Use the values from /pending-tools to correlate the results.",
"operationId": "submitRunToolResults",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsToolResultsRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsToolResultsResponse"
}
}
},
"description": "Tool results accepted"
},
"400": {
"description": "Invalid payload"
},
"404": {
"description": "Run or pending tool calls not found"
},
"409": {
"description": "Tool results conflict (wrong step/request_id)"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Submit tool results"
},
"parameters": [
{
"in": "path",
"name": "run_id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
]
},
"/workflows/compile": {
"post": {
"description": "Compiles a workflow spec into a canonical plan and plan hash. This validates the workflow schema and model capability constraints.",
"operationId": "compileWorkflow",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowSpec"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowsCompileResponse"
}
}
},
"description": "Compiled workflow"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
},
"description": "Invalid workflow spec or validation errors"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Compile a workflow spec"
}
},
"/workflows/lint": {
"post": {
"description": "Runs strict JSON schema linting on output_format.json_schema for LLM nodes and optionally compiles the workflow. Pass compile=false to skip compilation.",
"operationId": "lintWorkflow",
"parameters": [
{
"description": "Whether to compile the workflow after linting (default: true)",
"in": "query",
"name": "compile",
"required": false,
"schema": {
"type": "boolean",
"default": true
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowSpec"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkflowsLintResponse"
}
}
},
"description": "Lint results"
},
"400": {
"description": "Invalid payload"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"summary": "Lint a workflow spec"
}
},
"/messages": {
"get": {
"operationId": "listMessages",
"summary": "List messages",
"description": "List messages for an inbox address or a thread.",
"parameters": [
{
"in": "query",
"name": "to",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "thread_id",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"in": "query",
"name": "unread",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 200
}
},
{
"in": "query",
"name": "offset",
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
}
}
],
"responses": {
"200": {
"description": "Messages",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageListResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
]
},
"post": {
"operationId": "sendMessage",
"summary": "Send a message",
"description": "Send a message to a mailbox address.",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageSendRequest"
}
}
}
},
"responses": {
"201": {
"description": "Message",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
]
}
},
"/messages/{message_id}": {
"get": {
"operationId": "getMessage",
"summary": "Get a message",
"parameters": [
{
"in": "path",
"name": "message_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Message",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageResponse"
}
}
}
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
]
}
},
"/messages/{message_id}/read": {
"post": {
"operationId": "markMessageRead",
"summary": "Mark a message read",
"parameters": [
{
"in": "path",
"name": "message_id",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"204": {
"description": "Message marked as read"
}
},
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
]
}
}
},
"servers": [
{
"url": "https://api.modelrelay.ai/api/v1"
}
]
}