Models

Endpoints for managing AI models and their configurations.

GET /api/models

List available AI models with optional filtering.

Authentication: Required (session)

Query Parameters:

Parameter	Type	Default	Description
chat	boolean	false	Filter to chat-capable models
includeInternal	boolean	false	Include internal/system models

Response:

{
  "_links": {
    "self": { "href": "/api/models" }
  },
  "_embedded": {
    "inf:model": [
      {
        "id": "claude-opus-4",
        "name": "Claude Opus 4",
        "slug": "claude-opus-4",
        "description": "Most capable model for complex tasks",
        "providerId": "anthropic-123",
        "model": "claude-opus-4-20250514",
        "chat": true,
        "web": true,
        "generateImage": false,
        "attachments": true,
        "createEmbeddings": false,
        "tier": "strategic",
        "pricingTier": "Very High",
        "contextWindow": 200000,
        "maxOutputTokens": 16384,
        "promptPpm": 15.0,
        "completionPpm": 75.0,
        "cacheReadPpm": 1.5,
        "cacheWriteShortPpm": 18.75,
        "cacheWriteLongPpm": 15.0,
        "score": 95,
        "moderated": false,
        "internal": false,
        "deprecatedAt": null,
        "referencedModel": null
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

Model Properties:

Field	Type	Description
id	string	Unique model ID
name	string	Display name
slug	string	URL-safe identifier
description	string	Model description
providerId	string	Provider ID (for canonical models)
model	string	Provider's model identifier
referencesId	string	Referenced model ID (for alias models)
chat	boolean	Supports chat completions
web	boolean	Can access web content
generateImage	boolean	Can generate images
attachments	boolean	Supports file attachments
createEmbeddings	boolean	Can create embeddings
tier	string	Budget tier: everyday, advanced, strategic
pricingTier	string	Cost category: Low, Medium, High, Very High
contextWindow	integer	Maximum context tokens
maxOutputTokens	integer	Maximum output tokens
promptPpm	number	Cost per million prompt tokens
completionPpm	number	Cost per million completion tokens
cacheReadPpm	number	Cost per million cached read tokens
cacheWriteShortPpm	number	Cost per million short-term cache writes
cacheWriteLongPpm	number	Cost per million long-term cache writes
score	integer	Quality/capability score (0-100)
moderated	boolean	Content moderation enabled
internal	boolean	System-only model
deprecatedAt	date	Deprecation date (null if active)

Alias Models:

Models can reference other models via referencesId. Alias models:

• Inherit capabilities from referenced model
• Can override name, slug, and instructions
• Automatically adopt tier from base model if not specified
• Share provider with referenced model (set via trigger)

---

POST /api/models

Create a new AI model (canonical or alias).

Authentication: permission.ai.manage

Pre-blocks:

• permission.ai.manage
• Provider lookup (for canonical models)
• Referenced model lookup (for alias models)

Request Body (Canonical Model):

Field	Type	Required	Description
providerId	string	Yes	Provider ID
model	string	Yes	Provider's model identifier
name	string	Yes	Display name
slug	string	No	URL-safe ID (defaults to model)
description	string	No	Model description
chat	boolean	No	Supports chat
web	boolean	No	Web access capability
generateImage	boolean	No	Image generation
attachments	boolean	No	File attachment support
createEmbeddings	boolean	No	Embedding generation
tier	string	No	everyday, advanced, strategic
pricingTier	string	No	Low, Medium, High, Very High
contextWindow	integer	No	Max context tokens
maxOutputTokens	integer	No	Max output tokens
promptPpm	number	No	Prompt cost per million tokens
completionPpm	number	No	Completion cost per million tokens
cacheReadPpm	number	No	Cache read cost per million
cacheWriteShortPpm	number	No	Short cache write cost
cacheWriteLongPpm	number	No	Long cache write cost
score	integer	No	Quality score (0-100)
moderated	boolean	No	Content moderation
instructions	string	No	System instructions
options	object	No	Provider-specific options
deprecatedAt	date	No	Deprecation date

Request Body (Alias Model):

Field	Type	Required	Description
referencesId	string	Yes	Base model ID to reference
name	string	Yes	Display name for alias
slug	string	Yes	URL-safe identifier
instructions	string	No	Override instructions
options	object	No	Override options

Example (Canonical):

{
  "providerId": "anthropic-123",
  "model": "claude-3-5-sonnet-20241022",
  "name": "Claude 3.5 Sonnet",
  "slug": "claude-3-5-sonnet",
  "chat": true,
  "tier": "advanced",
  "contextWindow": 200000,
  "promptPpm": 3.0,
  "completionPpm": 15.0
}

Example (Alias):

{
  "referencesId": "claude-opus-4",
  "name": "Strategic Assistant",
  "slug": "strategic-assistant",
  "instructions": "Focus on strategic analysis"
}

Response:

Returns the created model object.

---

GET /api/models/{id}

Retrieve a single model with full details.

Authentication: Required (session)

Pre-blocks: model.lookup

Response:

Model object with all properties and referenced model (if alias).

---

PUT /api/models/{id}

Update a model's configuration.

Authentication: permission.ai.manage

Pre-blocks:

• model.lookup
• permission.ai.manage

Request Body:

Same fields as POST, except providerId, model, and referencesId cannot be changed.

Managed Model Restrictions:

Internal and managed models have restrictions:

• Cannot change providerId or model
• Can update options and pricing for key-only updates
• Cannot delete

Response:

Returns the updated model object.

---

DELETE /api/models/{id}

Delete a model.

Authentication: permission.ai.manage

Pre-blocks:

• model.lookup
• permission.ai.manage

Response:

204 No Content

Restrictions:

• Cannot delete managed models
• Cannot delete models currently in use by chats
• Deleting a model may orphan alias models

---

POST /api/models/{id}/_chat

Send a chat message directly to a model (bypasses chat history).

Authentication: Required (session with AI seat)

Pre-blocks:

• Model resolution
• Tier-based budget enforcement

Request Body:

Field	Type	Required	Description
messages	array	Yes	Array of message objects
system	string	No	System prompt
tools	array	No	Available tools
assistantIds	array	No	Assistants to load
datasetIds	array	No	Datasets to include
libraryIds	array	No	Libraries to include
toolkitIds	array	No	Toolkits to enable

Payload Limit: 200MB

Example Request:

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze this data..."
    }
  ],
  "system": "You are a data analyst",
  "assistantIds": ["asst-123"],
  "datasetIds": ["ds-456"]
}

Response:

Server-Sent Events (SSE) stream with chat completion.

Use Cases:

• One-off model queries without creating a chat
• Model testing and evaluation
• Skill-specific interactions
• Temporary analysis workflows

---

POST /api/models/{id}/_completion

Generate a text completion using a model.

Authentication: Required (session with AI seat)

Pre-blocks:

• Model resolution
• Tier-based budget enforcement

Request Body:

Field	Type	Required	Description
prompt	string	Yes	Completion prompt
messages	array	No	Optional message context
maxTokens	integer	No	Max tokens to generate
temperature	number	No	Sampling temperature (0-1)
stopSequences	array	No	Stop generation on these strings

Payload Limit: 200MB

Example Request:

{
  "prompt": "Complete this sentence: The future of AI is",
  "maxTokens": 100,
  "temperature": 0.7
}

Response:

Server-Sent Events (SSE) stream with completion text.

---

POST /api/models/{id}/_object

Generate a structured object from a model using JSON Schema.

Authentication: Required (session with AI seat)

Pre-blocks:

• Model resolution
• Tier-based budget enforcement

Request Body:

Field	Type	Required	Description
schema	object	Yes	JSON Schema for output structure
messages	array	Yes	Prompt messages
system	string	No	System prompt

Example Request:

{
  "schema": {
    "type": "object",
    "properties": {
      "sentiment": { "type": "string", "enum": ["positive", "negative", "neutral"] },
      "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
      "keywords": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["sentiment", "confidence"]
  },
  "messages": [
    {
      "role": "user",
      "content": "Analyze the sentiment: 'This product is amazing!'"
    }
  ]
}

Response:

{
  "sentiment": "positive",
  "confidence": 0.95,
  "keywords": ["amazing", "product"]
}

Validation:

• Output is validated against provided schema
• Invalid responses trigger retry (up to 3 attempts)
• Schema must be valid JSON Schema draft 2020-12

Use Cases:

• Extract structured data from text
• Classification tasks
• Sentiment analysis
• Entity extraction
• Data normalization

Model Selection

Use advanced or strategic tier models for complex schema generation. Everyday models may struggle with intricate structures.