{
"openapi": "3.0.3",
"info": {
"title": "ModelRelay API",
"version": "0.7.0",
"description": "Control-plane and inference endpoints for ModelRelay projects, tiers, customers, billing, and LLM proxying."
},
"servers": [
{
"url": "https://api.modelrelay.ai/api/v1"
}
],
"paths": {
"/schemas/workflow_v0.schema.json": {
"get": {
"operationId": "getWorkflowV0Schema",
"summary": "Get JSON Schema for workflow.v0",
"description": "Returns the canonical JSON Schema (draft-07) for `workflow.v0`.",
"responses": {
"200": {
"description": "Schema document",
"content": {
"application/schema+json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/schemas/run_event_v0.schema.json": {
"get": {
"operationId": "getRunEventV0Schema",
"summary": "Get JSON Schema for run_event.v0",
"description": "Returns the canonical JSON Schema (draft-07) for `run_event.v0` (workflow run history events).",
"responses": {
"200": {
"description": "Schema document",
"content": {
"application/schema+json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/auth/register": {
"post": {
"operationId": "registerOwner",
"summary": "Register a new owner account",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "User created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthResponse"
}
}
}
}
}
}
},
"/auth/login": {
"post": {
"operationId": "login",
"summary": "Exchange credentials for tokens",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"password": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Tokens issued",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthResponse"
}
}
}
}
}
}
},
"/auth/refresh": {
"post": {
"operationId": "refreshToken",
"summary": "Refresh an access token",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"refresh_token": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Tokens refreshed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuthTokens"
}
}
}
}
}
}
},
"/auth/logout": {
"post": {
"operationId": "logout",
"summary": "Revoke a refresh token",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"refresh_token": {
"type": "string"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Session revoked"
}
}
}
},
"/auth/me": {
"get": {
"operationId": "getAuthenticatedUser",
"summary": "Fetch the authenticated user profile",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Current user",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
}
}
}
}
}
}
}
}
},
"/auth/customer-token": {
"post": {
"operationId": "mintCustomerToken",
"summary": "Mint a customer-scoped bearer token",
"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",
"security": [
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"format": "uuid",
"description": "Internal customer UUID (provide exactly one of customer_id or customer_external_id)"
},
"customer_external_id": {
"type": "string",
"description": "External customer identifier (provide exactly one of customer_id or customer_external_id)"
},
"ttl_seconds": {
"type": "integer",
"format": "uint32",
"minimum": 1,
"description": "Requested token TTL in seconds (server may cap this)"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Customer token issued",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTokenResponse"
}
}
}
},
"400": {
"description": "Invalid request (missing or invalid customer selector)"
},
"401": {
"description": "Invalid or missing secret key"
},
"404": {
"description": "Customer not found"
}
}
}
},
"/auth/device/start": {
"post": {
"operationId": "startDeviceAuthorization",
"summary": "Start a device authorization session",
"description": "Starts an OAuth 2.0 device authorization session so constrained clients (TUIs)\ncan obtain a customer-scoped bearer token without running a local web server.\nRequires a project-scoped API key (publishable or secret).\n",
"security": [
{
"apiKeyAuth": []
}
],
"responses": {
"201": {
"description": "Device authorization session started",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceStartResponse"
}
}
}
},
"400": {
"description": "Invalid request (e.g., missing project-scoped API key)"
},
"401": {
"description": "Missing or invalid API key"
}
}
}
},
"/auth/device/token": {
"post": {
"operationId": "pollDeviceToken",
"summary": "Poll a device authorization session",
"description": "Polls a device authorization session by `device_code`. Returns a customer-scoped bearer token\nonce the user completes authorization in the browser.\n",
"security": [
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"device_code"
],
"properties": {
"device_code": {
"type": "string",
"description": "Opaque device code returned by /auth/device/start"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Customer token issued",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTokenResponse"
}
}
}
},
"400": {
"description": "OAuth device flow error (authorization_pending, slow_down, expired_token, invalid_grant, access_denied)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeviceTokenError"
}
}
}
},
"401": {
"description": "Missing or invalid API key"
}
}
}
},
"/auth/oidc/exchange": {
"post": {
"operationId": "exchangeOidcToken",
"summary": "Exchange an OIDC id_token for a customer bearer token",
"description": "Verifies a provided OIDC `id_token` using the project's configured OIDC settings,\nresolves (provider, subject) to a customer via customer_identities, and returns\na short-lived customer-scoped bearer token for data-plane access.\n",
"security": [
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"id_token"
],
"properties": {
"id_token": {
"type": "string",
"description": "OIDC id_token JWT to verify and exchange"
},
"project_id": {
"type": "string",
"format": "uuid",
"description": "Optional; must match the API key's project_id if provided"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Customer token issued",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerTokenResponse"
}
}
}
},
"400": {
"description": "Invalid request or token contents",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
},
"401": {
"description": "Invalid id_token"
},
"403": {
"description": "Identity unknown and auto-provision disabled",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIError"
}
}
}
},
"409": {
"description": "Identity already linked to a different customer"
}
}
}
},
"/customers/claim": {
"post": {
"operationId": "claimCustomer",
"summary": "Link a customer identity to a customer by email",
"description": "Used when a customer subscribes via Stripe Checkout (email only) and later authenticates to the app.\nLinks (provider, subject) to the existing customer record found by email.\n",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"email",
"provider",
"subject"
],
"properties": {
"email": {
"type": "string",
"format": "email"
},
"provider": {
"type": "string",
"enum": [
"github",
"google",
"oidc"
],
"description": "Identity provider (must match project's enabled providers)"
},
"subject": {
"type": "string",
"minLength": 1,
"description": "OAuth/OIDC subject claim from the identity provider"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Customer identity linked"
},
"404": {
"description": "Customer not found"
},
"409": {
"description": "Identity already linked to a different customer"
}
}
}
},
"/customers": {
"get": {
"operationId": "listCustomers",
"summary": "List customers",
"security": [
{
"apiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Customer list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
}
}
}
}
}
}
}
},
"post": {
"operationId": "createProjectCustomer",
"summary": "Create a customer",
"security": [
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerCreate"
}
}
}
},
"responses": {
"201": {
"description": "Customer created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
}
}
}
}
}
}
},
"put": {
"operationId": "upsertCustomer",
"summary": "Upsert a customer by external_id",
"security": [
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerCreate"
}
}
}
},
"responses": {
"200": {
"description": "Customer updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
}
}
}
}
},
"201": {
"description": "Customer created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
}
}
}
}
}
}
}
},
"/customers/{customer_id}": {
"parameters": [
{
"name": "customer_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"get": {
"operationId": "getCustomer",
"summary": "Get a customer",
"security": [
{
"apiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Customer",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
}
}
}
}
},
"404": {
"description": "Customer not found"
}
}
},
"delete": {
"operationId": "deleteProjectCustomer",
"summary": "Delete a customer",
"security": [
{
"apiKeyAuth": []
}
],
"responses": {
"204": {
"description": "Customer deleted"
},
"404": {
"description": "Customer not found"
}
}
}
},
"/customers/{customer_id}/subscribe": {
"parameters": [
{
"name": "customer_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"post": {
"operationId": "subscribeCustomer",
"summary": "Create a customer subscription checkout session",
"security": [
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"tier_id",
"success_url",
"cancel_url"
],
"properties": {
"tier_id": {
"type": "string",
"format": "uuid"
},
"success_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Checkout session created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutSessionResponse"
}
}
}
}
}
}
},
"/customers/{customer_id}/subscription": {
"parameters": [
{
"name": "customer_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"get": {
"operationId": "getCustomerSubscription",
"summary": "Get a customer's subscription",
"security": [
{
"apiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Subscription details",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscription": {
"$ref": "#/components/schemas/Subscription"
}
}
}
}
}
},
"404": {
"description": "Subscription not found"
}
}
},
"delete": {
"operationId": "cancelCustomerSubscription",
"summary": "Cancel a customer's subscription",
"security": [
{
"apiKeyAuth": []
}
],
"responses": {
"204": {
"description": "Subscription canceled"
}
}
}
},
"/customers/me": {
"get": {
"operationId": "getCustomerMe",
"summary": "Get the authenticated customer",
"description": "Returns the current customer associated with the provided customer-scoped bearer token.\nIncludes the customer's subscription and tier when available.\n",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Customer details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeResponse"
}
}
}
},
"401": {
"description": "Unauthorized"
}
}
}
},
"/customers/me/usage": {
"get": {
"operationId": "getCustomerMeUsage",
"summary": "Get the authenticated customer's usage",
"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",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Usage summary",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeUsageResponse"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer not found"
},
"500": {
"description": "Failed to calculate usage"
},
"503": {
"description": "Service unavailable"
}
}
}
},
"/customers/me/subscription": {
"get": {
"operationId": "getCustomerMeSubscription",
"summary": "Get the authenticated customer's subscription",
"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",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Subscription details",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerMeSubscriptionResponse"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"404": {
"description": "Customer or tier not found"
},
"500": {
"description": "Internal server error"
},
"503": {
"description": "Service unavailable"
}
}
}
},
"/models": {
"get": {
"operationId": "listModels",
"summary": "List active models",
"description": "Returns all active models with rich metadata for building model selectors.",
"parameters": [
{
"name": "provider",
"in": "query",
"required": false,
"description": "Filter results to a specific provider",
"schema": {
"$ref": "#/components/schemas/ProviderId"
}
},
{
"name": "capability",
"in": "query",
"required": false,
"description": "Filter results to models that support a capability",
"schema": {
"$ref": "#/components/schemas/ModelCapability"
}
}
],
"responses": {
"200": {
"description": "Models list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ModelsResponse"
}
}
}
}
}
}
},
"/projects": {
"get": {
"operationId": "listProjects",
"summary": "List projects for the authenticated owner",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Project list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"projects": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
}
}
}
}
}
}
}
},
"post": {
"operationId": "createProject",
"summary": "Create a project",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Project created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"project": {
"$ref": "#/components/schemas/Project"
}
}
}
}
}
}
}
}
},
"/projects/{id}": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"get": {
"operationId": "getProject",
"summary": "Get a project",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Project found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"project": {
"$ref": "#/components/schemas/Project"
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateProject",
"summary": "Update a project",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"customer_auto_provision_tier_id": {
"type": "string",
"format": "uuid"
},
"customer_oauth_providers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"github",
"google"
]
}
},
"oidc_enabled": {
"type": "boolean"
},
"oidc_issuer": {
"type": "string"
},
"oidc_audiences": {
"type": "array",
"items": {
"type": "string"
}
},
"oidc_jwks_url": {
"type": "string"
},
"oidc_subject_claim": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Project updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"project": {
"$ref": "#/components/schemas/Project"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteProject",
"summary": "Delete a project",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"204": {
"description": "Project deleted"
}
}
}
},
"/projects/{id}/tiers": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"get": {
"operationId": "listProjectTiers",
"summary": "List tiers for a project",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Tier list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tiers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tier"
}
}
}
}
}
}
}
}
},
"post": {
"operationId": "createTier",
"summary": "Create a tier",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TierCreate"
}
}
}
},
"responses": {
"201": {
"description": "Tier created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tier": {
"$ref": "#/components/schemas/Tier"
}
}
}
}
}
}
}
}
},
"/projects/{id}/tiers/{tier_id}": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"name": "tier_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"put": {
"operationId": "updateTier",
"summary": "Update a tier",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TierUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Tier updated"
}
}
},
"delete": {
"operationId": "deleteTier",
"summary": "Delete a tier",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"204": {
"description": "Tier deleted"
}
}
}
},
"/projects/{id}/customers": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"get": {
"operationId": "listProjectCustomers",
"summary": "List customers for a project",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Customer list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
}
}
}
}
}
}
}
},
"post": {
"operationId": "createCustomer",
"summary": "Create a customer",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CustomerCreate"
}
}
}
},
"responses": {
"201": {
"description": "Customer created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerWithSubscription"
}
}
}
}
}
}
}
}
},
"/projects/{id}/customers/{customer_id}": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"name": "customer_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"delete": {
"operationId": "deleteCustomer",
"summary": "Delete a customer",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"204": {
"description": "Customer deleted"
}
}
}
},
"/projects/{id}/webhooks": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
}
],
"get": {
"operationId": "listProjectWebhooks",
"summary": "List project webhooks",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Webhook list",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"webhooks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WebhookConfig"
}
}
}
}
}
}
}
}
},
"post": {
"operationId": "createProjectWebhook",
"summary": "Create a project webhook",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookConfigInput"
}
}
}
},
"responses": {
"201": {
"description": "Webhook created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"webhook": {
"$ref": "#/components/schemas/WebhookConfig"
}
}
}
}
}
}
}
}
},
"/projects/{id}/webhooks/{webhook_id}": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/WebhookID"
}
],
"get": {
"operationId": "getProjectWebhook",
"summary": "Get a project webhook",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"200": {
"description": "Webhook details",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"webhook": {
"$ref": "#/components/schemas/WebhookConfig"
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateProjectWebhook",
"summary": "Update a project webhook",
"security": [
{
"bearerAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookConfigUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Webhook updated",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"webhook": {
"$ref": "#/components/schemas/WebhookConfig"
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteProjectWebhook",
"summary": "Delete a project webhook",
"security": [
{
"bearerAuth": []
}
],
"responses": {
"204": {
"description": "Webhook deleted"
}
}
}
},
"/projects/{id}/webhooks/{webhook_id}/events": {
"parameters": [
{
"$ref": "#/components/parameters/ProjectID"
},
{
"$ref": "#/components/parameters/WebhookID"
}
],
"get": {
"operationId": "listProjectWebhookEvents",
"summary": "List webhook delivery events",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Webhook events",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OutboundWebhookEvent"
}
}
}
}
}
}
}
}
}
},
"/responses": {
"post": {
"operationId": "createResponse",
"summary": "Create a response via the provider-agnostic API",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesRequest"
}
}
}
},
"responses": {
"200": {
"description": "Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesResponse"
}
}
}
}
}
}
},
"/responses:batch": {
"post": {
"operationId": "createResponsesBatch",
"summary": "Create multiple responses concurrently (batch)",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesBatchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Batch response results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponsesBatchResponse"
}
}
}
}
}
}
},
"/images/generate": {
"post": {
"operationId": "generateImage",
"summary": "Generate images from a text prompt",
"description": "Generate images using AI models. Returns URLs by default (requires storage configuration) or base64-encoded data when response_format is 'b64_json'.",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageRequest"
}
}
}
},
"responses": {
"200": {
"description": "Generated images",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImageResponse"
}
}
}
}
}
}
},
"/runs": {
"post": {
"operationId": "createRun",
"summary": "Start a workflow run (workflow.v0)",
"description": "Starts a run for a `workflow.v0` spec and returns a `run_id`. Auth matches `/responses` (API key or frontend bearer token). Session owner tokens from `/auth/login` are not accepted.",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsCreateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Run created (or idempotent replay)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsCreateResponse"
}
}
}
}
}
}
},
"/runs/{run_id}": {
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"get": {
"operationId": "getRun",
"summary": "Get a derived run snapshot",
"description": "Returns a derived snapshot state for the run (folded from event history + artifacts), including outputs and an aggregated cost summary when available.",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Run snapshot",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunsGetResponse"
}
}
}
},
"404": {
"description": "Run not found"
}
}
}
},
"/runs/{run_id}/events": {
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "after_seq",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"description": "Returns events where `seq > after_seq`."
},
{
"name": "wait",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
},
"description": "When false, returns currently available events then closes."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "uint32",
"minimum": 1,
"maximum": 10000
},
"description": "Maximum number of events to send before closing."
}
],
"get": {
"operationId": "streamRunEvents",
"summary": "Stream run events (append-only)",
"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.v0` envelope; see `/schemas/run_event_v0.schema.json` for the canonical schema.",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Event stream (NDJSON or SSE)",
"content": {
"application/x-ndjson": {
"schema": {
"type": "string"
},
"example": "{\"envelope_version\":\"v0\",\"seq\":1,\"type\":\"run_compiled\",...}\n{\"envelope_version\":\"v0\",\"seq\":2,\"type\":\"run_started\",...}\n"
},
"text/event-stream": {
"schema": {
"type": "string"
},
"example": "event: run_started\nid: 2\ndata: {\"envelope_version\":\"v0\",\"seq\":2,\"type\":\"run_started\",...}\n"
}
}
}
}
}
},
"/sessions": {
"post": {
"operationId": "createSession",
"summary": "Create a new session",
"description": "Creates a new session for multi-turn conversation management. Sessions persist message history on the server for cross-device continuity.",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionCreateRequest"
}
}
}
},
"responses": {
"201": {
"description": "Session created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionResponse"
}
}
}
},
"400": {
"description": "Invalid request"
},
"401": {
"description": "API key required"
}
}
},
"get": {
"operationId": "listSessions",
"summary": "List sessions",
"description": "Returns a paginated list of sessions for the project.",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 100,
"default": 50
},
"description": "Maximum number of sessions to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Number of sessions to skip"
},
{
"name": "end_user_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Filter sessions by end user ID"
}
],
"responses": {
"200": {
"description": "Session list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionListResponse"
}
}
}
},
"401": {
"description": "API key required"
}
}
}
},
"/sessions/{session_id}": {
"parameters": [
{
"name": "session_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"get": {
"operationId": "getSession",
"summary": "Get session with messages",
"description": "Returns a session including its full message history.",
"security": [
{
"bearerAuth": []
},
{
"apiKeyAuth": []
}
],
"responses": {
"200": {
"description": "Session with messages",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionWithMessagesResponse"
}
}
}
},
"404": {
"description": "Session not found"
}
}
},
"delete": {
"operationId": "deleteSession",
"summary": "Delete a session",
"description": "Deletes a session and all its messages. Requires a secret API key (mr_sk_*).",
"security": [
{
"apiKeyAuth": []
}
],
"responses": {
"204": {
"description": "Session deleted"
},
"403": {
"description": "Secret key required for deletion"
},
"404": {
"description": "Session not found"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
},
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-ModelRelay-Api-Key"
}
},
"parameters": {
"ProjectID": {
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
"WebhookID": {
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
},
"schemas": {
"AuthTokens": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
},
"AuthResponse": {
"type": "object",
"properties": {
"user": {
"$ref": "#/components/schemas/User"
},
"tokens": {
"$ref": "#/components/schemas/AuthTokens"
},
"access_token": {
"type": "string"
},
"refresh_token": {
"type": "string"
}
}
},
"User": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"project_id": {
"type": "string",
"format": "uuid"
}
}
},
"Project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"owner_id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"customer_auto_provision_tier_id": {
"type": "string",
"format": "uuid"
},
"customer_oauth_providers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"github",
"google"
]
}
},
"oidc_enabled": {
"type": "boolean"
},
"oidc_issuer": {
"type": "string"
},
"oidc_audiences": {
"type": "array",
"items": {
"type": "string"
}
},
"oidc_jwks_url": {
"type": "string"
},
"oidc_subject_claim": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"PriceInterval": {
"type": "string",
"enum": [
"month",
"year"
],
"description": "Billing interval for a tier."
},
"TierModel": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"tier_id": {
"type": "string",
"format": "uuid"
},
"model_id": {
"$ref": "#/components/schemas/ModelId"
},
"model_display_name": {
"type": "string",
"description": "Human-friendly model name resolved from pricing (e.g., 'GPT-4o Mini')"
},
"description": {
"type": "string",
"description": "Human-friendly description of what the model is good at"
},
"capabilities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelCapability"
},
"description": "Workflow-critical capability flags for the model"
},
"context_window": {
"type": "integer",
"format": "int32",
"minimum": 0,
"description": "Maximum supported context window in tokens (if known)"
},
"max_output_tokens": {
"type": "integer",
"format": "int32",
"minimum": 0,
"description": "Maximum supported output tokens (if known)"
},
"deprecated": {
"type": "boolean",
"description": "Whether the model is deprecated"
},
"input_price_per_million_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Input token price in cents per million (e.g., 300 = $3.00/1M tokens)"
},
"output_price_per_million_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Output token price in cents per million (e.g., 1500 = $15.00/1M tokens)"
},
"is_default": {
"type": "boolean",
"description": "Whether this is the default model for the tier"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"tier_id",
"model_id",
"model_display_name",
"description",
"capabilities",
"context_window",
"max_output_tokens",
"deprecated",
"input_price_per_million_cents",
"output_price_per_million_cents",
"is_default",
"created_at",
"updated_at"
]
},
"TierModelCreate": {
"type": "object",
"properties": {
"model_id": {
"$ref": "#/components/schemas/ModelId"
},
"input_price_per_million_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"output_price_per_million_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"is_default": {
"type": "boolean",
"default": false
}
},
"required": [
"model_id",
"input_price_per_million_cents",
"output_price_per_million_cents"
]
},
"Tier": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"display_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Human-readable tier name"
},
"spend_limit_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Monthly spend limit in cents (e.g., 2000 = $20/month). Must be non-negative."
},
"models": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/TierModel"
}
},
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"billing_price_ref": {
"type": "string",
"description": "Billing provider price reference for this tier"
},
"price_amount_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Subscription price amount in cents"
},
"price_currency": {
"type": "string",
"description": "Currency code for the price (e.g., 'usd')"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"trial_days": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Number of trial days for new subscriptions"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"TierCreate": {
"type": "object",
"properties": {
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"display_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Human-readable tier name"
},
"spend_limit_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Monthly spend limit in cents (e.g., 2000 = $20/month). Must be non-negative."
},
"models": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/TierModelCreate"
}
},
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"price_amount_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Subscription price amount in cents (paid tiers)"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"trial_days": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Number of trial days for new subscriptions (paid tiers)"
}
},
"required": [
"tier_code",
"display_name",
"spend_limit_cents",
"models"
]
},
"TierUpdate": {
"type": "object",
"properties": {
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"display_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Human-readable tier name"
},
"spend_limit_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Monthly spend limit in cents (e.g., 2000 = $20/month). Must be non-negative."
},
"models": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/TierModelCreate"
}
},
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"price_amount_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Subscription price amount in cents (paid tiers)"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"trial_days": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Number of trial days for new subscriptions (paid tiers)"
}
},
"required": [
"tier_code",
"display_name",
"spend_limit_cents"
]
},
"CustomerMetadata": {
"type": "object",
"description": "Arbitrary customer metadata (max 10KB). Keys are limited to 40 characters. Values can be any JSON type. Nesting depth limited to 5 levels.",
"additionalProperties": true
},
"SubscriptionStatusKind": {
"type": "string",
"enum": [
"active",
"trialing",
"past_due",
"canceled",
"unpaid",
"incomplete",
"incomplete_expired",
"paused"
],
"description": "Subscription status (active, past_due, canceled, etc.)",
"x-rust-type": {
"crate": "modelrelay",
"version": "0.1",
"path": "modelrelay::SubscriptionStatusKind"
}
},
"BillingProvider": {
"type": "string",
"enum": [
"stripe",
"crypto",
"app_store",
"external"
],
"description": "Billing provider backing the subscription or tier."
},
"Customer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"external_id": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "External customer identifier from your system"
},
"email": {
"type": "string",
"format": "email",
"description": "Customer email address"
},
"metadata": {
"$ref": "#/components/schemas/CustomerMetadata"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"Subscription": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"customer_id": {
"type": "string",
"format": "uuid"
},
"tier_id": {
"type": "string",
"format": "uuid"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"billing_provider": {
"$ref": "#/components/schemas/BillingProvider"
},
"billing_customer_id": {
"type": "string",
"description": "Billing customer ID from the provider"
},
"billing_subscription_id": {
"type": "string",
"description": "Billing subscription ID from the provider"
},
"subscription_status": {
"$ref": "#/components/schemas/SubscriptionStatusKind"
},
"current_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current billing period"
},
"current_period_end": {
"type": "string",
"format": "date-time",
"description": "End of the current billing period"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"CustomerWithSubscription": {
"type": "object",
"required": ["customer"],
"properties": {
"customer": {
"$ref": "#/components/schemas/Customer"
},
"subscription": {
"$ref": "#/components/schemas/Subscription"
}
}
},
"CustomerMe": {
"type": "object",
"required": ["customer"],
"properties": {
"customer": {
"$ref": "#/components/schemas/Customer"
},
"subscription": {
"$ref": "#/components/schemas/Subscription"
},
"tier": {
"$ref": "#/components/schemas/Tier"
}
}
},
"CustomerMeResponse": {
"type": "object",
"properties": {
"customer": {
"$ref": "#/components/schemas/CustomerMe"
}
},
"required": [
"customer"
]
},
"CustomerUsagePoint": {
"type": "object",
"required": ["day", "requests", "tokens"],
"properties": {
"day": {
"type": "string",
"format": "date-time",
"description": "UTC day bucket"
},
"requests": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"tokens": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"images": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"credits_used_cents": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Credits used in this day bucket (only for paid tiers)"
}
}
},
"CustomerMeUsage": {
"type": "object",
"description": "Customer-visible usage metrics for the current billing window.",
"required": ["window_start", "window_end", "requests", "tokens", "images", "daily"],
"properties": {
"window_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current billing window"
},
"window_end": {
"type": "string",
"format": "date-time",
"description": "End of the current billing window"
},
"requests": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"tokens": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"images": {
"type": "integer",
"format": "int64",
"minimum": 0
},
"credits_granted_cents": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Credits granted for this billing window (only for paid tiers)"
},
"credits_used_cents": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Credits used so far in this billing window (only for paid tiers)"
},
"credits_remaining_cents": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Credits remaining in this billing window (only for paid tiers)"
},
"percentage_used": {
"type": "number",
"format": "float",
"minimum": 0,
"maximum": 100,
"description": "Percentage of granted credits used (only for paid tiers)"
},
"low": {
"type": "boolean",
"description": "Whether remaining credits are low (only for paid tiers)"
},
"daily": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomerUsagePoint"
}
}
}
},
"CustomerMeUsageResponse": {
"type": "object",
"required": ["usage"],
"properties": {
"usage": {
"$ref": "#/components/schemas/CustomerMeUsage"
}
}
},
"CustomerMeSubscription": {
"type": "object",
"description": "Customer-visible subscription details for the current tier.",
"required": ["tier_code", "tier_display_name"],
"properties": {
"tier_code": {
"$ref": "#/components/schemas/TierCode"
},
"tier_display_name": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Human-readable tier name"
},
"price_amount_cents": {
"type": "integer",
"format": "int64",
"minimum": 0,
"description": "Subscription price amount in cents (omitted for free tiers)"
},
"price_currency": {
"type": "string",
"description": "Currency code for the price (e.g., 'usd')"
},
"price_interval": {
"$ref": "#/components/schemas/PriceInterval"
},
"subscription_status": {
"$ref": "#/components/schemas/SubscriptionStatusKind"
},
"current_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current billing period"
},
"current_period_end": {
"type": "string",
"format": "date-time",
"description": "End of the current billing period"
}
}
},
"CustomerMeSubscriptionResponse": {
"type": "object",
"required": ["subscription"],
"properties": {
"subscription": {
"$ref": "#/components/schemas/CustomerMeSubscription"
}
}
},
"CustomerCreate": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "External customer identifier from your system"
},
"email": {
"type": "string",
"format": "email",
"description": "Customer email address"
},
"metadata": {
"$ref": "#/components/schemas/CustomerMetadata"
}
},
"required": [
"external_id",
"email"
]
},
"MessageRole": {
"type": "string",
"enum": [
"system",
"user",
"assistant",
"tool"
]
},
"ContentPart": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"text"
]
},
"text": {
"type": "string"
}
}
},
"InputItem": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"message"
]
},
"role": {
"$ref": "#/components/schemas/MessageRole"
},
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ContentPart"
}
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToolCall"
}
},
"tool_call_id": {
"$ref": "#/components/schemas/ToolCallId"
}
}
},
"OutputItem": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"message"
]
},
"role": {
"$ref": "#/components/schemas/MessageRole"
},
"content": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ContentPart"
}
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToolCall"
}
}
}
},
"JSONSchemaFormat": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"schema": {
"type": "object",
"additionalProperties": true
},
"strict": {
"type": "boolean"
}
}
},
"OutputFormat": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"json_schema"
]
},
"json_schema": {
"$ref": "#/components/schemas/JSONSchemaFormat"
}
}
},
"Tool": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"function",
"web",
"x_search",
"code_execution",
"image_generation"
]
},
"function": {
"type": "object",
"properties": {
"name": {
"$ref": "#/components/schemas/ToolName"
},
"description": {
"type": "string"
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
},
"web": {
"type": "object",
"additionalProperties": true
},
"x_search": {
"type": "object",
"additionalProperties": true
},
"code_execution": {
"type": "object",
"additionalProperties": true
},
"image_generation": {
"type": "object",
"description": "Configuration for server-side image generation tool",
"required": ["model"],
"properties": {
"model": {
"type": "string",
"description": "Image generation model ID (e.g., gemini-2.5-flash-image)"
}
}
}
}
},
"ToolChoice": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"auto",
"required",
"none"
]
},
"function": {
"$ref": "#/components/schemas/ToolName"
}
}
},
"ResponsesRequest": {
"type": "object",
"required": [
"input"
],
"properties": {
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"input": {
"type": "array",
"items": {
"$ref": "#/components/schemas/InputItem"
}
},
"output_format": {
"$ref": "#/components/schemas/OutputFormat"
},
"max_output_tokens": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"temperature": {
"type": "number"
},
"stop": {
"type": "array",
"items": {
"type": "string"
}
},
"tools": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Tool"
}
},
"tool_choice": {
"$ref": "#/components/schemas/ToolChoice"
}
}
},
"ResponsesResponse": {
"type": "object",
"required": [
"id",
"output",
"model",
"usage"
],
"properties": {
"id": {
"type": "string",
"description": "Response identifier from the provider"
},
"output": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OutputItem"
}
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"stop_reason": {
"type": "string",
"description": "Why generation stopped (stop, max_tokens, tool_use, etc.)"
},
"usage": {
"$ref": "#/components/schemas/Usage"
},
"citations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Citation"
},
"description": "Sources from web search results"
}
}
},
"JSONPatchOperation": {
"type": "object",
"required": [
"op",
"path"
],
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
]
},
"path": {
"type": "string"
},
"from": {
"type": "string"
},
"value": {
"type": "object",
"additionalProperties": true
}
}
},
"ResponsesStreamEnvelope": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"enum": [
"start",
"update",
"completion",
"error",
"keepalive",
"tool_use_start",
"tool_use_delta",
"tool_use_stop"
]
},
"stream_mode": {
"type": "string",
"enum": [
"text-delta",
"structured-patch"
]
},
"stream_version": {
"type": "string",
"enum": [
"v2"
]
},
"delta": {
"type": "string"
},
"content": {
"type": "string"
},
"patch": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JSONPatchOperation"
}
},
"payload": {
"type": "object",
"additionalProperties": true
},
"complete_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"status": {
"type": "integer"
},
"request_id": {
"type": "string"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"stop_reason": {
"type": "string"
},
"usage": {
"$ref": "#/components/schemas/Usage"
}
}
},
"ResponsesBatchRequest": {
"type": "object",
"required": [
"requests"
],
"properties": {
"requests": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResponsesRequest"
}
},
"options": {
"type": "object",
"properties": {
"max_parallelism": {
"type": "integer",
"format": "uint32",
"minimum": 1,
"maximum": 100
},
"abort_on_error": {
"type": "boolean"
}
}
}
}
},
"ResponsesBatchError": {
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"type": "integer"
},
"message": {
"type": "string"
},
"detail": {
"type": "string",
"description": "Raw error details from the provider"
},
"code": {
"type": "string"
}
}
},
"ResponsesBatchResult": {
"type": "object",
"required": [
"index",
"ok"
],
"properties": {
"index": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"ok": {
"type": "boolean"
},
"response": {
"$ref": "#/components/schemas/ResponsesResponse"
},
"error": {
"$ref": "#/components/schemas/ResponsesBatchError"
}
}
},
"ResponsesBatchResponse": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResponsesBatchResult"
}
},
"request_id": {
"type": "string"
}
}
},
"WorkflowSpecV0": {
"type": "object",
"description": "A `workflow.v0` spec. The canonical JSON Schema is available at `/schemas/workflow_v0.schema.json`.",
"additionalProperties": true
},
"RunsCreateOptionsV0": {
"type": "object",
"properties": {
"idempotency_key": {
"type": "string"
}
}
},
"RunsCreateRequest": {
"type": "object",
"required": [
"spec"
],
"properties": {
"spec": {
"$ref": "#/components/schemas/WorkflowSpecV0"
},
"input": {
"type": "object",
"description": "Reserved for future use.",
"additionalProperties": true
},
"options": {
"$ref": "#/components/schemas/RunsCreateOptionsV0"
}
}
},
"RunStatusV0": {
"type": "string",
"enum": [
"running",
"waiting",
"succeeded",
"failed",
"canceled"
]
},
"RunsCreateResponse": {
"type": "object",
"required": [
"run_id",
"status",
"plan_hash"
],
"properties": {
"run_id": {
"$ref": "#/components/schemas/RunId"
},
"status": {
"$ref": "#/components/schemas/RunStatusV0"
},
"plan_hash": {
"$ref": "#/components/schemas/PlanHash"
}
}
},
"NodeStatusV0": {
"type": "string",
"enum": [
"pending",
"running",
"waiting",
"succeeded",
"failed",
"canceled"
]
},
"NodeErrorV0": {
"type": "object",
"required": [
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"detail": {
"type": "string",
"description": "Raw error details from the provider"
}
}
},
"NodeResultV0": {
"type": "object",
"required": [
"id",
"type",
"status"
],
"properties": {
"id": {
"$ref": "#/components/schemas/NodeId"
},
"type": {
"$ref": "#/components/schemas/NodeTypeV0"
},
"status": {
"$ref": "#/components/schemas/NodeStatusV0"
},
"started_at": {
"type": "string",
"format": "date-time"
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"output": {
"type": "object",
"additionalProperties": true
},
"error": {
"$ref": "#/components/schemas/NodeErrorV0"
}
}
},
"RunCostLineItemV0": {
"type": "object",
"required": [
"provider_id",
"model",
"requests",
"input_tokens",
"output_tokens",
"usd_cents"
],
"properties": {
"provider_id": {
"$ref": "#/components/schemas/ProviderId"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"requests": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"input_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"output_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"usd_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0
}
}
},
"RunCostSummaryV0": {
"type": "object",
"required": [
"total_usd_cents"
],
"properties": {
"total_usd_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"line_items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunCostLineItemV0"
}
}
}
},
"RunsGetResponse": {
"type": "object",
"required": [
"run_id",
"status",
"plan_hash",
"cost_summary"
],
"properties": {
"run_id": {
"$ref": "#/components/schemas/RunId"
},
"status": {
"$ref": "#/components/schemas/RunStatusV0"
},
"plan_hash": {
"$ref": "#/components/schemas/PlanHash"
},
"cost_summary": {
"$ref": "#/components/schemas/RunCostSummaryV0"
},
"nodes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NodeResultV0"
}
},
"outputs": {
"type": "object",
"additionalProperties": true
}
}
},
"Usage": {
"type": "object",
"description": "Token usage statistics. All fields default to 0 if not present.",
"properties": {
"input_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"default": 0
},
"output_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"default": 0
},
"total_tokens": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"default": 0
}
}
},
"ToolCallId": {
"type": "string",
"description": "Unique identifier for a tool call. Treated as an opaque string and must be preserved exactly.",
"minLength": 1,
"maxLength": 256
},
"ToolName": {
"type": "string",
"description": "Tool identifier. For tools.v0 client tools, use dot-separated lowercase segments (e.g. fs.search).",
"pattern": "^[a-z][a-z0-9_]*(\\\\.[a-z][a-z0-9_]*)*$",
"minLength": 1,
"maxLength": 128
},
"ToolCall": {
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"$ref": "#/components/schemas/ToolCallId"
},
"type": {
"type": "string",
"enum": [
"function",
"web",
"x_search",
"code_execution",
"image_generation"
]
},
"function": {
"type": "object",
"properties": {
"name": {
"$ref": "#/components/schemas/ToolName"
},
"arguments": {
"type": "string",
"description": "JSON string of function arguments"
}
}
}
}
},
"Citation": {
"type": "object",
"properties": {
"url": {
"type": "string"
},
"title": {
"type": "string"
}
}
},
"CustomerTokenResponse": {
"type": "object",
"required": [
"token",
"expires_at",
"expires_in",
"project_id",
"customer_id",
"customer_external_id",
"tier_code"
],
"properties": {
"token": {
"type": "string",
"description": "The customer bearer token"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Token expiration timestamp"
},
"expires_in": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Seconds until token expires"
},
"project_id": {
"type": "string",
"format": "uuid",
"description": "Project the token is scoped to"
},
"customer_id": {
"type": "string",
"format": "uuid",
"description": "Internal customer UUID"
},
"customer_external_id": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "External customer identifier"
},
"tier_code": {
"$ref": "#/components/schemas/TierCode"
}
}
},
"CheckoutSessionResponse": {
"type": "object",
"required": [
"session_id",
"url"
],
"properties": {
"session_id": {
"type": "string",
"description": "Stripe checkout session ID"
},
"url": {
"type": "string",
"format": "uri",
"description": "Checkout URL"
}
}
},
"DeviceStartResponse": {
"type": "object",
"required": [
"device_code",
"user_code",
"verification_uri",
"expires_in",
"interval"
],
"properties": {
"device_code": {
"type": "string",
"description": "Device code used for polling /auth/device/token"
},
"user_code": {
"type": "string",
"description": "Human-enterable code shown to the user"
},
"verification_uri": {
"type": "string",
"description": "URL where the user enters the code and completes authorization"
},
"verification_uri_complete": {
"type": "string",
"description": "Convenience URL that pre-fills the user_code (optional)"
},
"expires_in": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Seconds until the device code expires"
},
"interval": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Minimum polling interval in seconds"
}
}
},
"DeviceTokenError": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "OAuth device flow error code"
},
"error_description": {
"type": "string",
"description": "Optional human-readable error message"
},
"interval": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Updated recommended polling interval in seconds (when error is slow_down)"
}
}
},
"APIError": {
"type": "object",
"required": [
"error",
"code",
"message"
],
"properties": {
"error": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"SubscriptionStatus": {
"type": "object",
"description": "Subscription status for a customer.",
"required": [
"active"
],
"properties": {
"active": {
"type": "boolean",
"description": "Whether the subscription is currently active"
},
"subscription_id": {
"type": "string",
"description": "Stripe subscription ID"
},
"status": {
"$ref": "#/components/schemas/SubscriptionStatusKind"
},
"current_period_start": {
"type": "string",
"format": "date-time",
"description": "Start of the current billing period"
},
"current_period_end": {
"type": "string",
"format": "date-time",
"description": "End of the current billing period"
}
}
},
"RunsPendingToolsResponse": {
"type": "object",
"description": "Response containing pending tool calls for a workflow run.",
"required": [
"run_id"
],
"properties": {
"run_id": {
"$ref": "#/components/schemas/RunId"
},
"pending": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunsPendingToolsNodeV0"
}
}
}
},
"RunsPendingToolsNodeV0": {
"type": "object",
"description": "A node with pending tool calls.",
"required": [
"node_id",
"step",
"request_id"
],
"properties": {
"node_id": {
"$ref": "#/components/schemas/NodeId"
},
"step": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The step number within the node execution"
},
"request_id": {
"$ref": "#/components/schemas/RequestId"
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RunsPendingToolCallV0"
}
}
}
},
"RunsPendingToolCallV0": {
"type": "object",
"description": "A pending tool call waiting for a result.",
"required": [
"tool_call_id",
"name",
"arguments"
],
"properties": {
"tool_call_id": {
"$ref": "#/components/schemas/ToolCallId",
"description": "Unique identifier for this tool call"
},
"name": {
"$ref": "#/components/schemas/ToolName",
"description": "Name of the tool to be called"
},
"arguments": {
"type": "string",
"description": "JSON-encoded arguments for the tool call"
}
}
},
"NDJSONStreamEvent": {
"type": "object",
"description": "Events sent during streaming responses (application/x-ndjson).\nEach line is a JSON object with an \"event\" field indicating the type.\n",
"required": [
"event"
],
"properties": {
"event": {
"type": "string",
"enum": [
"message_start",
"message_delta",
"message_stop",
"tool_use_start",
"tool_use_delta",
"tool_use_stop",
"ping",
"keepalive"
],
"description": "Event type"
},
"response_id": {
"type": "string",
"description": "Response identifier (message_start)"
},
"model": {
"$ref": "#/components/schemas/ModelId"
},
"text_delta": {
"type": "string",
"description": "Text content fragment (message_delta)"
},
"stop_reason": {
"type": "string",
"description": "Why generation stopped (message_stop)"
},
"usage": {
"$ref": "#/components/schemas/Usage"
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToolCall"
},
"description": "Completed tool calls (tool_use_stop, message_stop)"
},
"tool_call_delta": {
"$ref": "#/components/schemas/ToolCallDelta"
}
}
},
"ToolCallDelta": {
"type": "object",
"description": "Incremental tool call data during streaming",
"properties": {
"index": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"id": {
"$ref": "#/components/schemas/ToolCallId"
},
"type": {
"type": "string"
},
"function": {
"type": "object",
"properties": {
"name": {
"$ref": "#/components/schemas/ToolName"
},
"arguments": {
"type": "string",
"description": "Partial JSON string"
}
}
}
}
},
"NodeId": {
"type": "string",
"description": "Workflow node identifier. Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.",
"pattern": "^[a-z][a-z0-9_]*$",
"minLength": 1,
"maxLength": 64
},
"ModelId": {
"type": "string",
"description": "LLM model identifier (e.g., claude-sonnet-4-20250514, gpt-4o).",
"minLength": 1,
"maxLength": 128
},
"ModelCapability": {
"type": "string",
"description": "Workflow-critical model capability identifier.",
"enum": [
"tools",
"vision",
"web_search",
"web_fetch",
"computer_use",
"code_execution"
]
},
"Model": {
"type": "object",
"properties": {
"model_id": {
"$ref": "#/components/schemas/ModelId"
},
"provider": {
"$ref": "#/components/schemas/ProviderId"
},
"display_name": {
"type": "string"
},
"description": {
"type": "string"
},
"capabilities": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ModelCapability"
}
},
"context_window": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"max_output_tokens": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"training_cutoff": {
"type": "string",
"description": "Training cutoff in YYYY-MM format"
},
"deprecated": {
"type": "boolean"
},
"deprecation_message": {
"type": "string"
},
"input_cost_per_million_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"output_cost_per_million_cents": {
"type": "integer",
"format": "uint64",
"minimum": 0
}
},
"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"
]
},
"ModelsResponse": {
"type": "object",
"properties": {
"models": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Model"
}
}
},
"required": [
"models"
]
},
"RunId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for a workflow run."
},
"RequestId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for an LLM request within a workflow run."
},
"PlanHash": {
"type": "string",
"description": "SHA-256 hash of the compiled workflow plan (64 hex characters).",
"pattern": "^[a-f0-9]{64}$",
"minLength": 64,
"maxLength": 64
},
"Sha256Hash": {
"type": "string",
"description": "SHA-256 hash (64 hex characters).",
"pattern": "^[a-f0-9]{64}$",
"minLength": 64,
"maxLength": 64
},
"ProviderId": {
"type": "string",
"enum": [
"anthropic",
"openai",
"xai",
"google-ai-studio"
],
"description": "LLM provider identifier."
},
"PluginManifestV0": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"version": {
"type": "string"
},
"commands": {
"type": "array",
"items": {
"type": "string"
}
},
"agents": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"PluginGitHubRefV0": {
"type": "object",
"properties": {
"owner": {
"type": "string"
},
"repo": {
"type": "string"
},
"ref": {
"type": "string"
},
"path": {
"type": "string"
}
}
},
"PluginCommandV0": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"prompt": {
"type": "string"
},
"agent_refs": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"name",
"prompt"
]
},
"PluginAgentV0": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"system_prompt": {
"type": "string"
}
},
"required": [
"name",
"system_prompt"
]
},
"WebhookConfig": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"project_id": {
"type": "string",
"format": "uuid"
},
"endpoint_url": {
"type": "string",
"format": "uri"
},
"signing_secret": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"customer.created",
"customer.updated",
"customer.deleted",
"usage.threshold_exceeded",
"request.completed",
"billing.subscription_changed"
]
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"WebhookConfigInput": {
"type": "object",
"properties": {
"endpoint_url": {
"type": "string",
"format": "uri"
},
"enabled": {
"type": "boolean"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"customer.created",
"customer.updated",
"customer.deleted",
"usage.threshold_exceeded",
"request.completed",
"billing.subscription_changed"
]
}
}
},
"required": [
"endpoint_url",
"events"
]
},
"WebhookConfigUpdate": {
"type": "object",
"properties": {
"endpoint_url": {
"type": "string",
"format": "uri"
},
"enabled": {
"type": "boolean"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"customer.created",
"customer.updated",
"customer.deleted",
"usage.threshold_exceeded",
"request.completed",
"billing.subscription_changed"
]
}
},
"rotate_secret": {
"type": "boolean"
}
},
"required": [
"endpoint_url",
"events"
]
},
"OutboundWebhookEvent": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"webhook_config_id": {
"type": "string",
"format": "uuid"
},
"event_type": {
"type": "string"
},
"event_id": {
"type": "string"
},
"payload": {
"type": "object"
},
"status": {
"type": "string"
},
"attempt_count": {
"type": "integer",
"format": "int32"
},
"next_attempt_at": {
"type": "string",
"format": "date-time"
},
"last_attempt_at": {
"type": "string",
"format": "date-time"
},
"response_status": {
"type": "integer",
"format": "int32"
},
"response_body": {
"type": "string"
},
"latency_ms": {
"type": "integer",
"format": "int32"
},
"error": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
},
"NodeTypeV0": {
"type": "string",
"enum": [
"llm.responses",
"join.all",
"transform.json"
],
"description": "Type of workflow node."
},
"TierCode": {
"type": "string",
"description": "Tier code identifier (e.g., free, pro, enterprise).",
"minLength": 1,
"maxLength": 64,
"pattern": "^[a-z][a-z0-9_-]*$"
},
"ImageRequest": {
"type": "object",
"description": "Request to generate images from a text prompt.",
"properties": {
"model": {
"type": "string",
"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."
},
"prompt": {
"type": "string",
"description": "Text description of the image to generate"
},
"response_format": {
"$ref": "#/components/schemas/ImageResponseFormat"
}
},
"required": [
"prompt"
]
},
"ImageResponseFormat": {
"type": "string",
"description": "Output format for generated images.",
"enum": [
"url",
"b64_json"
],
"default": "url"
},
"ImageResponse": {
"type": "object",
"description": "Response containing generated images.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for this generation request"
},
"model": {
"type": "string",
"description": "Model used for generation"
},
"data": {
"type": "array",
"description": "Generated images",
"items": {
"$ref": "#/components/schemas/ImageData"
}
},
"usage": {
"$ref": "#/components/schemas/ImageUsage"
}
},
"required": [
"id",
"model",
"data",
"usage"
]
},
"ImageData": {
"type": "object",
"description": "A single generated image.",
"properties": {
"url": {
"type": "string",
"description": "URL of the generated image (when response_format is 'url')"
},
"b64_json": {
"type": "string",
"description": "Base64-encoded image data (when response_format is 'b64_json')"
},
"mime_type": {
"type": "string",
"description": "MIME type of the image (e.g., 'image/png', 'image/webp')"
}
}
},
"ImageUsage": {
"type": "object",
"description": "Usage statistics for image generation.",
"properties": {
"images": {
"type": "integer",
"format": "int32",
"description": "Number of images generated"
}
},
"required": [
"images"
]
},
"SessionCreateRequest": {
"type": "object",
"description": "Request body for creating a session.",
"properties": {
"end_user_id": {
"type": "string",
"format": "uuid",
"description": "Optional end user ID to associate with the session"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Optional metadata for the session"
}
}
},
"SessionResponse": {
"type": "object",
"description": "A session resource.",
"required": [
"id",
"project_id",
"metadata",
"message_count",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Session unique identifier"
},
"project_id": {
"type": "string",
"format": "uuid",
"description": "Project the session belongs to"
},
"end_user_id": {
"type": "string",
"format": "uuid",
"description": "End user associated with the session (if any)"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Session metadata"
},
"message_count": {
"type": "integer",
"format": "int64",
"description": "Number of messages in the session"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Session creation timestamp"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Session last update timestamp"
}
}
},
"SessionMessageResponse": {
"type": "object",
"description": "A message within a session.",
"required": [
"id",
"seq",
"role",
"content",
"created_at"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Message unique identifier"
},
"seq": {
"type": "integer",
"format": "int32",
"description": "Sequence number within the session"
},
"role": {
"type": "string",
"description": "Message role (user, assistant, tool)"
},
"content": {
"type": "array",
"description": "Message content parts",
"items": {
"type": "object",
"additionalProperties": true
}
},
"run_id": {
"type": "string",
"format": "uuid",
"description": "Run ID that generated this message (for assistant messages)"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Message creation timestamp"
}
}
},
"SessionWithMessagesResponse": {
"type": "object",
"description": "A session with its full message history.",
"allOf": [
{
"$ref": "#/components/schemas/SessionResponse"
},
{
"type": "object",
"required": [
"messages"
],
"properties": {
"messages": {
"type": "array",
"description": "All messages in the session",
"items": {
"$ref": "#/components/schemas/SessionMessageResponse"
}
}
}
}
]
},
"SessionListResponse": {
"type": "object",
"description": "Paginated list of sessions.",
"required": [
"sessions"
],
"properties": {
"sessions": {
"type": "array",
"description": "List of sessions",
"items": {
"$ref": "#/components/schemas/SessionResponse"
}
},
"next_cursor": {
"type": "string",
"description": "Cursor for fetching the next page (if more results exist)"
}
}
}
}
}
}