Models

Looking for the product view?

The Help Center explains this surface as users see it: Choosing the right model.

Endpoints for managing AI models and for running one-off calls against a model. A model is either canonical (it points at a Provider plus a provider-side model identifier) or an alias (it references another model via referencesId and inherits that model's provider and capabilities).

Listing and reading models is open to any authenticated user. Creating, updating, and deleting models require permission.ai.manage (superuser). None of these routes require the AI module to be enabled on the tenant.

GET /api/models

List the tenant's models.

Authentication: Required (no permission gate)

Query Parameters:

Parameter	Type	Default	Description
`chat`	boolean	false	Keep only chat-capable models. Alias models inherit the referenced model's `chat` flag.
`includeInternal`	boolean	false	Include internal/system models. Excluded by default.

Response:

A HAL-wrapped collection: a top-level { start, count, total } envelope with the models under _embedded["inf:model"]. It is not a hand-shaped document and there is no inf:model key at the document root. Canonical models eager-load their provider; alias models eager-load referencedModel.

List modelsGET /api/models

GET /api/models has no permission gate (any authenticated user). The body is an eu.collection: { items, start, count, total }, not a hand-shaped HAL doc. By default internal models are excluded; pass ?includeInternal=true to include them and ?chat=true to keep only chat-capable models (alias models inherit the referenced model’s chat flag).

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/models"
    }
  },
  "start": 0,
  "count": 5,
  "total": 5,
  "_embedded": {
    "inf:model": [
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/models/00000000-0000-4000-8000-000000000001"
          }
        },
        "naturalId": "go_advanced",
        "permissions": {},
        "promptPpm": null,
        "completionPpm": null,
        "cacheReadPpm": null,
        "cacheWriteShortPpm": null,
        "cacheWriteLongPpm": null,
        "tenant": "acme",
        "id": "00000000-0000-4000-8000-000000000001",
        "providerId": null,
        "referencesId": null,
        "name": "go_advanced",
        "slug": "go_advanced",
        "model": null,
        "options": null,
        "chat": false,
        "moderated": false,
        "contextWindow": 200000,
        "maxOutputTokens": null,
        "instructions": null,
        "description": null,
        "managed": true,
        "internal": false,
        "deprecatedAt": null,
        "web": false,
        "attachments": false,
        "generateImage": false,
        "createEmbeddings": false,
        "score": null,
        "pricingTier": null,
        "badges": null,
        "tier": null,
        "customized": false,
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "referencedModel": null,
        "provider": null
      },
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/models/00000000-0000-4000-8000-000000000002"
          }
        },
        "naturalId": "go_everyday",
        "permissions": {},
        "promptPpm": null,
        "completionPpm": null,
        "cacheReadPpm": null,
        "cacheWriteShortPpm": null,
        "cacheWriteLongPpm": null,
        "tenant": "acme",
        "id": "00000000-0000-4000-8000-000000000002",
        "providerId": null,
        "referencesId": null,
        "name": "go_everyday",
        "slug": "go_everyday",
        "model": null,
        "options": null,
        "chat": false,
        "moderated": false,
        "contextWindow": 200000,
        "maxOutputTokens": null,
        "instructions": null,
        "description": null,
        "managed": true,
        "internal": false,
        "deprecatedAt": null,
        "web": false,
        "attachments": false,
        "generateImage": false,
        "createEmbeddings": false,
        "score": null,
        "pricingTier": null,
        "badges": null,
        "tier": null,
        "customized": false,
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "referencedModel": null,
        "provider": null
      },
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/models/00000000-0000-4000-8000-000000000003"
          }
        },
        "naturalId": "informer-basic",
        "permissions": {},
        "promptPpm": 0.4,
        "completionPpm": 1.6,
        "cacheReadPpm": null,
        "cacheWriteShortPpm": null,
        "cacheWriteLongPpm": null,
        "tenant": "acme",
        "id": "00000000-0000-4000-8000-000000000003",
        "providerId": "00000000-0000-4000-8000-000000000004",
        "referencesId": null,
        "name": "Informer Basic",
        "slug": "informer-basic",
        "model": "gpt-4.1",
        "options": null,
        "chat": true,
        "moderated": false,
        "contextWindow": 200000,
        "maxOutputTokens": null,
        "instructions": null,
        "description": null,
        "managed": true,
        "internal": false,
        "deprecatedAt": null,
        "web": false,
        "attachments": false,
        "generateImage": false,
        "createEmbeddings": false,
        "score": null,
        "pricingTier": null,
        "badges": null,
        "tier": null,
        "customized": false,
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "referencedModel": null,
        "provider": {
          "permissions": {},
          "tenant": "acme",
          "id": "00000000-0000-4000-8000-000000000004",
          "name": "OpenAI",
          "slug": "openai",
          "type": "openai",
          "key": null,
          "managed": true,
          "internal": false,
          "settings": null,
          "data": null,
          "createdAt": "2026-01-15T16:20:00.000Z",
          "updatedAt": "2026-01-15T16:20:00.000Z"
        }
      },
      "… 2 more items (5 total) — omitted from docs"
    ]
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

Model properties:

Field	Type	Description
`id`	string (UUID)	Model id
`naturalId`	string	Stable natural identifier
`name`	string	Display name
`slug`	string	URL-safe identifier
`description`	string \| null	Model description
`providerId`	string (UUID) \| null	Owning Provider (canonical models)
`referencesId`	string (UUID) \| null	Base model id (alias models)
`model`	string \| null	Provider's model identifier
`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
`moderated`	boolean	Content moderation enabled
`tier`	string \| null	Budget tier: `everyday`, `advanced`, `strategic`
`pricingTier`	string \| null	Cost category: `Low`, `Medium`, `High`, `Very High`
`contextWindow`	integer \| null	Maximum context tokens
`maxOutputTokens`	integer \| null	Maximum output tokens
`promptPpm`	number \| null	Cost per million prompt tokens
`completionPpm`	number \| null	Cost per million completion tokens
`cacheReadPpm`	number \| null	Cost per million cached read tokens
`cacheWriteShortPpm`	number \| null	Cost per million short-term cache writes
`cacheWriteLongPpm`	number \| null	Cost per million long-term cache writes
`score`	integer \| null	Quality/capability score
`badges`	array \| null	Display badges
`instructions`	string \| null	System instructions
`options`	object \| null	Provider-specific options
`managed`	boolean	System-managed (License Manager controlled)
`internal`	boolean	Internal/system-only model
`customized`	boolean	Whether a managed model has been customized
`deprecatedAt`	date \| null	Deprecation date (null if active)
`provider`	object \| null	Eager-loaded Provider (canonical models)
`referencedModel`	object \| null	Eager-loaded base model (alias models)

Alias models:

Alias models reference another model via referencesId. They:

Inherit capabilities from the referenced model.
Can override name, slug, instructions, and options.
Take their providerId and model from the referenced model via a database trigger, so those are never sent when creating an alias.

POST /api/models

Create a model (canonical or alias).

Authentication: permission.ai.manage

Pre-blocks: permission.ai.manage

The payload is an XOR. If referencesId is present it is treated as an alias payload and only { referencesId, name, slug, instructions, options } are kept; every other field is stripped. Otherwise it is a canonical payload requiring { providerId, model, name }. Both referencesId and providerId must be UUIDs.

Request Body (canonical):

Field	Type	Required	Description
`providerId`	string (UUID)	Yes	Owning Provider
`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
`generateImage`	boolean	No	Image generation
`attachments`	boolean	No	File attachment support
`createEmbeddings`	boolean	No	Embedding generation
`moderated`	boolean	No	Content moderation
`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 per million
`cacheWriteLongPpm`	number	No	Long cache write cost per million
`score`	integer	No	Quality score
`instructions`	string	No	System instructions
`options`	object	No	Provider-specific options
`deprecatedAt`	date	No	Deprecation date

Example (canonical):

{
  "providerId": "00000000-0000-4000-8000-000000000001",
  "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
}

Response:

Responds 200 with the created model. The handler returns the new row directly, so there is no 201 status and no Location header.

Create a canonical modelPOST /api/models

Canonical payload requires { providerId (uuid), model, name }; slug defaults to `model`. Capability flags (chat/web/generateImage/attachments/createEmbeddings) and pricing/tier fields are optional. Requires permission.ai.manage. Responds 200 with the created Model (no 201, no Location header).

Request body

{
  "providerId": "00000000-0000-4000-8000-000000000001",
  "model": "claude-3-5-sonnet-20241022",
  "name": "Claude 3.5 Sonnet",
  "slug": "claude-3-5-sonnet",
  "chat": true,
  "tier": "advanced",
  "contextWindow": 200000,
  "promptPpm": 3,
  "completionPpm": 15
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/models"
    }
  },
  "naturalId": "claude-35-sonnet",
  "permissions": {},
  "promptPpm": 3,
  "completionPpm": 15,
  "cacheReadPpm": null,
  "cacheWriteShortPpm": null,
  "cacheWriteLongPpm": null,
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000002",
  "web": false,
  "attachments": false,
  "generateImage": false,
  "createEmbeddings": false,
  "customized": false,
  "name": "Claude 3.5 Sonnet",
  "slug": "claude-35-sonnet",
  "chat": true,
  "tier": "advanced",
  "contextWindow": 200000,
  "providerId": "00000000-0000-4000-8000-000000000001",
  "model": "claude-3-5-sonnet-20241022",
  "referencesId": null,
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "options": null,
  "instructions": null,
  "moderated": false,
  "internal": false,
  "description": null,
  "deprecatedAt": null,
  "managed": false,
  "score": null,
  "pricingTier": null,
  "badges": null,
  "maxOutputTokens": null
}

Captured from the API examples test suite; ids and timestamps are normalized.

Request Body (alias):

Field	Type	Required	Description
`referencesId`	string (UUID)	Yes	Base model id to reference
`name`	string	Yes	Display name for the alias
`slug`	string	Yes	URL-safe identifier
`instructions`	string	No	Override instructions
`options`	object	No	Override options

Example (alias):

{
  "referencesId": "00000000-0000-4000-8000-000000000002",
  "name": "Strategic Assistant",
  "slug": "strategic-assistant",
  "instructions": "Focus on strategic analysis"
}

Response:

Responds 200 with the created alias. Its providerId and model are filled in from the referenced model by a database trigger.

Create an alias modelPOST /api/models

Alias payload (referencesId present) only permits { referencesId (uuid, required), name (required), slug (required), instructions?, options? }; every other field is stripped. The alias’s providerId/model are filled by a DB trigger from the referenced model, so they are not sent here.

Request body

{
  "referencesId": "00000000-0000-4000-8000-000000000001",
  "name": "Strategic Assistant",
  "slug": "strategic-assistant",
  "instructions": "Focus on strategic analysis"
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/models"
    }
  },
  "naturalId": "strategic-assistant",
  "permissions": {},
  "promptPpm": 15,
  "completionPpm": 75,
  "cacheReadPpm": null,
  "cacheWriteShortPpm": null,
  "cacheWriteLongPpm": null,
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000002",
  "web": false,
  "attachments": false,
  "generateImage": false,
  "createEmbeddings": false,
  "customized": false,
  "name": "Strategic Assistant",
  "slug": "strategic-assistant",
  "instructions": null,
  "referencesId": "00000000-0000-4000-8000-000000000001",
  "model": "claude-opus-4-20250514",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "providerId": "00000000-0000-4000-8000-000000000003",
  "options": null,
  "moderated": false,
  "chat": true,
  "internal": false,
  "contextWindow": 200000,
  "description": null,
  "deprecatedAt": null,
  "managed": false,
  "score": 95,
  "pricingTier": "Very High",
  "badges": null,
  "maxOutputTokens": 16384,
  "tier": "strategic"
}

Captured from the API examples test suite; ids and timestamps are normalized.

GET /api/models/{id}

Retrieve a single model.

Authentication: Required (no permission gate)

Pre-blocks: model.lookup

The id may be a UUID or a slug. Canonical models return their eager-loaded provider; alias models return referencedModel.

Response:

Get a modelGET /api/models/00000000-0000-4000-8000-000000000001

GET /api/models/{id} resolves via the model.lookup pre (id may be a uuid or a slug). No permission gate. Returns the Model with its eager-loaded provider.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/models/00000000-0000-4000-8000-000000000001"
    }
  },
  "naturalId": "claude-opus-4",
  "permissions": {},
  "promptPpm": 15,
  "completionPpm": 75,
  "cacheReadPpm": null,
  "cacheWriteShortPpm": null,
  "cacheWriteLongPpm": null,
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000001",
  "providerId": "00000000-0000-4000-8000-000000000002",
  "referencesId": null,
  "name": "Claude Opus 4",
  "slug": "claude-opus-4",
  "model": "claude-opus-4-20250514",
  "options": null,
  "chat": true,
  "moderated": false,
  "contextWindow": 200000,
  "maxOutputTokens": 16384,
  "instructions": null,
  "description": null,
  "managed": false,
  "internal": false,
  "deprecatedAt": null,
  "web": false,
  "attachments": false,
  "generateImage": false,
  "createEmbeddings": false,
  "score": 95,
  "pricingTier": "Very High",
  "badges": null,
  "tier": "strategic",
  "customized": false,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "provider": {
    "permissions": {},
    "tenant": "acme",
    "id": "00000000-0000-4000-8000-000000000002",
    "name": "Anthropic",
    "slug": "anthropic",
    "type": "anthropic",
    "key": null,
    "managed": true,
    "internal": false,
    "settings": null,
    "data": null,
    "createdAt": "2026-01-15T16:20:00.000Z",
    "updatedAt": "2026-01-15T16:20:00.000Z"
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

PUT /api/models/{id}

Update a model.

Authentication: permission.ai.manage

Pre-blocks: permission.ai.manage, then model.lookup

Unknown fields are stripped. providerId, model, and referencesId can be sent but are ignored for non-managed edits. Returns the updated model.

Request Body:

The same optional fields as the canonical create payload, minus the identity fields above.

Example:

{ "description": "Updated description", "score": 90 }

Response:

Responds 200 with the updated model.

Update a modelPUT /api/models/00000000-0000-4000-8000-000000000001

PUT /api/models/{id} pre-blocks are permission.ai.manage THEN model.lookup. Unknown fields are stripped; providerId/model/referencesId can be sent but are ignored for non-managed edits. Managed models are read-only (403) outside the tier-alias carve-outs. Returns the updated Model.

Request body

{
  "description": "Updated description",
  "score": 90
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/models/00000000-0000-4000-8000-000000000001"
    }
  },
  "naturalId": "claude-opus-4",
  "permissions": {},
  "promptPpm": 15,
  "completionPpm": 75,
  "cacheReadPpm": null,
  "cacheWriteShortPpm": null,
  "cacheWriteLongPpm": null,
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000001",
  "providerId": "00000000-0000-4000-8000-000000000002",
  "referencesId": null,
  "name": "Claude Opus 4",
  "slug": "claude-opus-4",
  "model": "claude-opus-4-20250514",
  "options": null,
  "chat": true,
  "moderated": false,
  "contextWindow": 200000,
  "maxOutputTokens": 16384,
  "instructions": null,
  "description": "Updated description",
  "managed": false,
  "internal": false,
  "deprecatedAt": null,
  "web": false,
  "attachments": false,
  "generateImage": false,
  "createEmbeddings": false,
  "score": 90,
  "pricingTier": "Very High",
  "badges": null,
  "tier": "strategic",
  "customized": false,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "provider": {
    "permissions": {},
    "tenant": "acme",
    "id": "00000000-0000-4000-8000-000000000002",
    "name": "Anthropic",
    "slug": "anthropic",
    "type": "anthropic",
    "key": null,
    "managed": true,
    "internal": false,
    "settings": null,
    "data": null,
    "createdAt": "2026-01-15T16:20:00.000Z",
    "updatedAt": "2026-01-15T16:20:00.000Z"
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

Managed models are read-only

Managed models (those controlled by License Manager) reject edits with 403, except for the tier-alias customization carve-outs.

DELETE /api/models/{id}

Delete a model.

Authentication: permission.ai.manage

Pre-blocks: permission.ai.manage, then model.lookup

Response:

Responds 200 with an empty body (Informer convention), not 204 No Content.

Delete a modelDELETE /api/models/00000000-0000-4000-8000-000000000001

DELETE /api/models/{id} requires permission.ai.manage. The handler destroys the row and returns nothing, so the response is 200 with an EMPTY body (Informer convention), NOT 204. Managed models cannot be deleted (403).

Response · 200 · no body

Captured from the API examples test suite; ids and timestamps are normalized.

Managed models cannot be deleted

Deleting a managed model answers 403. Deleting a canonical model may orphan alias models that reference it.

POST /api/models/{id}/_chat

Run a one-off chat against a model without persisting a chat history.

Authentication: Required (AI access)

Pre-blocks: Model resolution, credit enforcement (model tier access and credit limits)

Metering: Consumes credits subject to the caller's usage profile (skipped under BYOK).

Request Body:

Field	Type	Required	Description
`messages`	array	Yes	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:

A live model stream (text/event-stream); not shown.

POST /api/models/{id}/_completion

Generate a text completion from a model.

Authentication: Required (AI access)

Pre-blocks: Model resolution, credit enforcement (model tier access and credit limits)

Metering: Consumes credits subject to the caller's usage profile (skipped under BYOK).

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
`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:

A live model stream (text/event-stream); not shown.

POST /api/models/{id}/_object

Generate a structured object from a model using a JSON Schema.

Authentication: Required (AI access)

Pre-blocks: Model resolution, credit enforcement (model tier access and credit limits)

Metering: Consumes credits subject to the caller's usage profile (skipped under BYOK).

Request Body:

Field	Type	Required	Description
`schema`	object	Yes	JSON Schema describing the 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:

A live model call validated against the supplied schema; not shown.

Model selection

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

GET /api/models​

POST /api/models​

GET /api/models/{id}​

PUT /api/models/{id}​

DELETE /api/models/{id}​

POST /api/models/{id}/_chat​

POST /api/models/{id}/_completion​

POST /api/models/{id}/_object​

GET /api/models

POST /api/models

GET /api/models/{id}

PUT /api/models/{id}

DELETE /api/models/{id}

POST /api/models/{id}/_chat

POST /api/models/{id}/_completion

POST /api/models/{id}/_object