# Models

## List models

`$ cadenya models list`

**get** `/v1/models`

Lists all models in the workspace

### Parameters

- `--cursor: optional string`

  Pagination cursor from previous response

- `--limit: optional number`

  Maximum number of results to return

- `--prefix: optional string`

  Filter by name prefix

- `--sort-order: optional string`

  Sort order for results (asc or desc by creation time)

- `--status: optional "MODEL_STATUS_UNSPECIFIED" or "MODEL_STATUS_ENABLED" or "MODEL_STATUS_DISABLED"`

  Filter by model status

### Returns

- `ListModelsResponse: object { items, pagination }`

  List models response

  - `items: optional array of Model`

    - `metadata: object { id, accountId, createdAt, 5 more }`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

      - `id: string`

        Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

      - `accountId: string`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `createdAt: string`

        Timestamp when this resource was created

      - `name: string`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profileId: string`

        ID of the actor (user or service account) that created this resource

      - `workspaceId: string`

        Workspace this resource belongs to for organizational grouping (prefixed ULID)

      - `externalId: optional string`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: optional map[string]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: object { family, inputPricePerMillionTokens, maxInputTokens, 4 more }`

      Model specification

      - `family: optional string`

        The model family (e.g., "claude-sonnet-4.6", "gpt-5.4", "gemini-2.5-flash")

      - `inputPricePerMillionTokens: optional string`

        Cost per million input tokens in cents (e.g., 300 = $3.00)

      - `maxInputTokens: optional number`

        Maximum number of input tokens the model supports

      - `maxOutputTokens: optional number`

        Maximum number of output tokens the model can generate

      - `outputPricePerMillionTokens: optional string`

        Cost per million output tokens in cents (e.g., 1500 = $15.00)

      - `provider: optional string`

        The model provider (e.g., "anthropic", "openai", "google")

      - `status: optional "MODEL_STATUS_UNSPECIFIED" or "MODEL_STATUS_ENABLED" or "MODEL_STATUS_DISABLED"`

        The status of the model in the workspace

        - `"MODEL_STATUS_UNSPECIFIED"`

        - `"MODEL_STATUS_ENABLED"`

        - `"MODEL_STATUS_DISABLED"`

  - `pagination: optional object { nextCursor, total }`

    - `nextCursor: optional string`

    - `total: optional number`

### Example

```cli
cadenya models list \
  --api-key 'My API Key'
```

#### Response

```json
{
  "items": [
    {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "family": "family",
        "inputPricePerMillionTokens": "inputPricePerMillionTokens",
        "maxInputTokens": 0,
        "maxOutputTokens": 0,
        "outputPricePerMillionTokens": "outputPricePerMillionTokens",
        "provider": "provider",
        "status": "MODEL_STATUS_UNSPECIFIED"
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Get a model by ID

`$ cadenya models retrieve`

**get** `/v1/models/{id}`

Retrieves a model by ID from the workspace

### Parameters

- `--id: string`

  Model ID

### Returns

- `model: object { metadata, spec }`

  - `metadata: object { id, accountId, createdAt, 5 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: object { family, inputPricePerMillionTokens, maxInputTokens, 4 more }`

    Model specification

    - `family: optional string`

      The model family (e.g., "claude-sonnet-4.6", "gpt-5.4", "gemini-2.5-flash")

    - `inputPricePerMillionTokens: optional string`

      Cost per million input tokens in cents (e.g., 300 = $3.00)

    - `maxInputTokens: optional number`

      Maximum number of input tokens the model supports

    - `maxOutputTokens: optional number`

      Maximum number of output tokens the model can generate

    - `outputPricePerMillionTokens: optional string`

      Cost per million output tokens in cents (e.g., 1500 = $15.00)

    - `provider: optional string`

      The model provider (e.g., "anthropic", "openai", "google")

    - `status: optional "MODEL_STATUS_UNSPECIFIED" or "MODEL_STATUS_ENABLED" or "MODEL_STATUS_DISABLED"`

      The status of the model in the workspace

      - `"MODEL_STATUS_UNSPECIFIED"`

      - `"MODEL_STATUS_ENABLED"`

      - `"MODEL_STATUS_DISABLED"`

### Example

```cli
cadenya models retrieve \
  --api-key 'My API Key' \
  --id id
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "family": "family",
    "inputPricePerMillionTokens": "inputPricePerMillionTokens",
    "maxInputTokens": 0,
    "maxOutputTokens": 0,
    "outputPricePerMillionTokens": "outputPricePerMillionTokens",
    "provider": "provider",
    "status": "MODEL_STATUS_UNSPECIFIED"
  }
}
```

## Set model status

`$ cadenya models set-status`

**put** `/v1/models/{id}/status`

Enables or disables a model in the workspace

### Parameters

- `--id: string`

  Model ID

- `--status: optional "MODEL_STATUS_UNSPECIFIED" or "MODEL_STATUS_ENABLED" or "MODEL_STATUS_DISABLED"`

  The new status for the model

### Returns

- `model: object { metadata, spec }`

  - `metadata: object { id, accountId, createdAt, 5 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: object { family, inputPricePerMillionTokens, maxInputTokens, 4 more }`

    Model specification

    - `family: optional string`

      The model family (e.g., "claude-sonnet-4.6", "gpt-5.4", "gemini-2.5-flash")

    - `inputPricePerMillionTokens: optional string`

      Cost per million input tokens in cents (e.g., 300 = $3.00)

    - `maxInputTokens: optional number`

      Maximum number of input tokens the model supports

    - `maxOutputTokens: optional number`

      Maximum number of output tokens the model can generate

    - `outputPricePerMillionTokens: optional string`

      Cost per million output tokens in cents (e.g., 1500 = $15.00)

    - `provider: optional string`

      The model provider (e.g., "anthropic", "openai", "google")

    - `status: optional "MODEL_STATUS_UNSPECIFIED" or "MODEL_STATUS_ENABLED" or "MODEL_STATUS_DISABLED"`

      The status of the model in the workspace

      - `"MODEL_STATUS_UNSPECIFIED"`

      - `"MODEL_STATUS_ENABLED"`

      - `"MODEL_STATUS_DISABLED"`

### Example

```cli
cadenya models set-status \
  --api-key 'My API Key' \
  --id id
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "family": "family",
    "inputPricePerMillionTokens": "inputPricePerMillionTokens",
    "maxInputTokens": 0,
    "maxOutputTokens": 0,
    "outputPricePerMillionTokens": "outputPricePerMillionTokens",
    "provider": "provider",
    "status": "MODEL_STATUS_UNSPECIFIED"
  }
}
```

## Domain Types

### Model

- `model: object { metadata, spec }`

  - `metadata: object { id, accountId, createdAt, 5 more }`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: string`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `accountId: string`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `createdAt: string`

      Timestamp when this resource was created

    - `name: string`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profileId: string`

      ID of the actor (user or service account) that created this resource

    - `workspaceId: string`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `externalId: optional string`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: optional map[string]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: object { family, inputPricePerMillionTokens, maxInputTokens, 4 more }`

    Model specification

    - `family: optional string`

      The model family (e.g., "claude-sonnet-4.6", "gpt-5.4", "gemini-2.5-flash")

    - `inputPricePerMillionTokens: optional string`

      Cost per million input tokens in cents (e.g., 300 = $3.00)

    - `maxInputTokens: optional number`

      Maximum number of input tokens the model supports

    - `maxOutputTokens: optional number`

      Maximum number of output tokens the model can generate

    - `outputPricePerMillionTokens: optional string`

      Cost per million output tokens in cents (e.g., 1500 = $15.00)

    - `provider: optional string`

      The model provider (e.g., "anthropic", "openai", "google")

    - `status: optional "MODEL_STATUS_UNSPECIFIED" or "MODEL_STATUS_ENABLED" or "MODEL_STATUS_DISABLED"`

      The status of the model in the workspace

      - `"MODEL_STATUS_UNSPECIFIED"`

      - `"MODEL_STATUS_ENABLED"`

      - `"MODEL_STATUS_DISABLED"`

### Model Spec

- `model_spec: object { family, inputPricePerMillionTokens, maxInputTokens, 4 more }`

  - `family: optional string`

    The model family (e.g., "claude-sonnet-4.6", "gpt-5.4", "gemini-2.5-flash")

  - `inputPricePerMillionTokens: optional string`

    Cost per million input tokens in cents (e.g., 300 = $3.00)

  - `maxInputTokens: optional number`

    Maximum number of input tokens the model supports

  - `maxOutputTokens: optional number`

    Maximum number of output tokens the model can generate

  - `outputPricePerMillionTokens: optional string`

    Cost per million output tokens in cents (e.g., 1500 = $15.00)

  - `provider: optional string`

    The model provider (e.g., "anthropic", "openai", "google")

  - `status: optional "MODEL_STATUS_UNSPECIFIED" or "MODEL_STATUS_ENABLED" or "MODEL_STATUS_DISABLED"`

    The status of the model in the workspace

    - `"MODEL_STATUS_UNSPECIFIED"`

    - `"MODEL_STATUS_ENABLED"`

    - `"MODEL_STATUS_DISABLED"`