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",
  "isSystemModel": false,
  "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
default:4096

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.

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

4096

8192

32768

128000

​
maxTokensPerRequest
integer | null

Upper bound for tokens the model may generate in a single response. If not specified, inherits from parent model. Keep this below contextWindow to leave room for prompts and history.

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

​
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."