Skip to content
SupaCloud Docs
Select themeSelect language

post_api_models_catalog_refresh

POST
/api/models/catalog/refresh
curl --request POST \
  --url https://example.com/api/models/catalog/refresh

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
fetched_at
required
string | null format: date-time
last_error
string | null
providers
required
Array<object>
object
id
required
string
models
required
Array<object>
object
available_modes

Axis 2 (mig 272) — the model’s harness-native available_modes (Claude ['build','plan']), joined from model_capabilities. None until a probe has landed; the FE then hides the Mode picker (degrade).

Array<string> | null
context
integer | null format: int32
cost
One of:
null
id
required
string
modalities_input
required
Array<string>
modalities_output
required
Array<string>
name
required
string
reasoning
required
boolean
supported_effort_levels

#626 D4.0 — the model’s HARNESS-NATIVE effort ladder (advertised order), joined from the model_capabilities table (the runner’s task-START capability probe). None until a probe has landed for this (provider, model_id) — the FE then degrades the EffortSlider to the canonical 5-step scale. The top stage (ultracode/ultra) is the last element when the harness presents it.

Array<string> | null
supports_fast_mode

#626 D4.0 — the model’s supports_fast_mode capability flag, joined from model_capabilities. None until a probe has landed.

boolean | null
supports_subagents

Axis 1 (mig 272) — the model’s supports_subagents capability flag, joined from model_capabilities. None until a probe has landed; the FE then hides the subagent toggle (degrade). Some(true) only on Claude in v1.

boolean | null
tool_call
required
boolean
name
required
string
refresh_interval_hours
required
integer format: int32
source
required
string
Examplegenerated
{
  "fetched_at": "2026-04-15T12:00:00Z",
  "last_error": "example",
  "providers": [
    {
      "id": "example",
      "models": [
        {
          "available_modes": [
            "example"
          ],
          "context": 1,
          "cost": {
            "cache_read": 1,
            "cache_write": 1,
            "input": 1,
            "note": "example",
            "output": 1
          },
          "id": "example",
          "modalities_input": [
            "example"
          ],
          "modalities_output": [
            "example"
          ],
          "name": "example",
          "reasoning": true,
          "supported_effort_levels": [
            "example"
          ],
          "supports_fast_mode": true,
          "supports_subagents": true,
          "tool_call": true
        }
      ],
      "name": "example"
    }
  ],
  "refresh_interval_hours": 1,
  "source": "example"
}

400

Section titled “400”

Structured client error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

401

Section titled “401”

Authentication required

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

403

Section titled “403”

Permission denied

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

500

Section titled “500”

Structured server error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}