Skip to main content
POST
/
v1
/
models
Create Model
curl --request POST \
  --url https://api.cuadra.ai/v1/models \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parentModelId": "<string>",
  "displayName": "<string>",
  "contextWindow": 4096,
  "maxTokensPerRequest": 1000,
  "supportsStreaming": true,
  "enabled": true,
  "metadata": "<unknown>",
  "systemPromptId": "550e8400-e29b-41d4-a716-446655440002",
  "systemPrompt": "<string>"
}
'
{
  "contextWindow": 128000,
  "createdAt": "2025-09-08T06:33:19Z",
  "creditMultiplier": 2,
  "description": "Advanced language model for complex tasks",
  "displayName": "large-model Omni",
  "enabled": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isRecommended": true,
  "isSystemModel": false,
  "lifecycleState": "active",
  "maxTokensPerRequest": 4096,
  "metadata": {},
  "modelName": "large-modelo",
  "provider": "provider-a",
  "supportsStreaming": true,
  "updatedAt": "2025-09-08T06:33:19Z"
}

Authorizations

​
Authorization
string
header
required

JWT token from Stytch B2B authentication (magic link, SSO, or M2M)

Headers

​
Idempotency-Key
string | null

Body

application/json

Schema for creating a new AI model configuration. Enterprise-grade validation with comprehensive field documentation for automatic OpenAPI generation.

​
parentModelId
string
required

ID of the system model to use as the base. User models must reference a system model to inherit pricing and capabilities.

Required string length: 1 - 36
Example:

"550e8400-e29b-41d4-a716-446655440000"

​
displayName
string
required

Your model's human-readable name shown in dashboards and responses (e.g., 'AI models Omni', 'My Finance Model'). Use this to differentiate organization-specific or customized variants.

Required string length: 1 - 200
Examples:

"large-model Omni"

"reasoning-model 3.5 Sonnet"

"Custom Support Model"

​
contextWindow
integer | null

Maximum tokens considered at once, including system prompt, message history, user input, tools/functions, and the model's output. Larger windows allow longer context but may increase cost/latency. If not specified, inherits from parent model.

Required range: 1 <= x <= 2000000
Example:

4096

​
maxTokensPerRequest
integer | null

Upper bound for tokens the model may generate in a single response (output tokens only, distinct from the context window). If not specified, inherits from parent model.

Required range: 1 <= x <= 200000
Example:

1000

​
supportsStreaming
boolean
default:true

Whether the provider/model supports SSE (Server-Sent Events) streaming responses.

​
enabled
boolean
default:true

Enable/disable this model for your organization without deleting it.

​
metadata
any
​
systemPromptId
string | null

ID of a system prompt composition to use for this model. System prompts are composed from particles (role, tone, guardrails, etc.).

Example:

"550e8400-e29b-41d4-a716-446655440002"

​
systemPrompt
string | null

Full system prompt override (escape hatch). If set, bypasses particle-based composition and uses this text directly.

Maximum string length: 50000

Response

Successful Response

Schema for AI model response data.

​
id
string
required

Unique identifier for the model

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
displayName
string
required

Human-readable display name

Examples:

"large-model Omni"

"reasoning-model 3.5 Sonnet"

​
contextWindow
integer
required

Model's context window size in tokens

Examples:

4096

128000

​
supportsStreaming
boolean
required

Whether the model supports streaming

Example:

true

​
enabled
boolean
required

Whether the model is enabled

Example:

true

​
isSystemModel
boolean
required

Whether this is a company-provided base model

Examples:

true

false

​
createdAt
string<date-time>
required

When the model was created

Example:

"2025-09-08T06:33:19Z"

​
updatedAt
string<date-time>
required

When the model was last updated

Example:

"2025-09-08T06:33:19Z"

​
description
string | null

Model description

Example:

"Advanced language model for complex tasks"

​
provider
string | null

AI provider name (NULL for user models, inherited from parent)

Example:

"provider-a"

​
modelName
string | null

Provider-specific model identifier (NULL for user models, inherited from parent)

Example:

"large-modelo"

​
maxTokensPerRequest
integer | null

Maximum tokens per request

Example:

4096

​
supportsTools
boolean
default:false

Whether the model supports tool/function calling

Examples:

true

false

​
supportsVision
boolean
default:false

Whether the model supports vision/image inputs

Examples:

true

false

​
supportsReasoning
boolean
default:false

Whether the model supports reasoning/thinking tokens (AI models extended thinking, o1, AI models thinking)

Examples:

true

false

​
creditMultiplier
integer | null

Credit multiplier for billing (system models only, user models inherit from parent)

Example:

1

​
modelTier
string
default:standard

Access tier for this model. 'standard' models are available on all plans. 'premium' models require a Pro or Enterprise subscription.

Examples:

"standard"

"premium"

​
lifecycleState
enum<string>
default:active

Current lifecycle state of the model. 'active': normal operation. 'disabled': temporarily disabled by admin. 'deprecated': end-of-life date is scheduled (see endOfLifeAt). 'end_of_life': model has been retired and should no longer be used.

Available options:
active,
disabled,
deprecated,
end_of_life
Examples:

"active"

"deprecated"

"end_of_life"

​
endOfLifeAt
string<date-time> | null

Scheduled end-of-life date for this model. When set and in the future, the model is deprecated. When in the past, the model has reached end of life. Null means the model has no scheduled retirement.

Example:

"2026-06-01T00:00:00Z"

​
deprecationMessage
string | null

User-facing deprecation notice. Typically includes a reason and a suggested replacement model. Only present when lifecycleState is 'deprecated' or 'end_of_life'.

Example:

"This model is scheduled for retirement on 2026-06-01. Please migrate to large-modelo."

​
replacementModelId
string | null

ID of the suggested replacement model when this model is deprecated or end-of-life. Use this to guide users toward a migration path. Null when no replacement is designated.

Example:

"660e8400-e29b-41d4-a716-446655440001"

​
isRecommended
boolean
default:false

Whether this model is recommended for new configurations. Curated by Cuadra — typically the best balance of capability, speed, and cost for each provider.

Examples:

true

false

​
metadata
any
​
parentModelId
string | null

ID of the parent system model (for user models)

Example:

"550e8400-e29b-41d4-a716-446655440001"

​
systemPromptId
string | null

ID of the system prompt composition assigned to this model

Example:

"550e8400-e29b-41d4-a716-446655440002"

​
systemPrompt
string | null

Full system prompt override (if set, bypasses particle composition)

Example:

"You are a helpful assistant."