---
title: "Settings API: models, version and diagnostics"
description: "Halo HTTP API for settings and models: version, model sources and switching models, security policy, agent engines and MCP server diagnostics."
type: "reference"
audience: ["developer"]
lang: "en"
canonical: "https://hello-halo.cc/docs/en/developers/api/settings.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# API: Settings and models

Halo HTTP API for settings and models: version, model sources and switching models, security policy, agent engines and MCP server diagnostics.

Read how this Halo is configured and what it can do — version, model sources and models, security policy, agent engines and MCP server diagnostics — and switch the model source and model. Credentials such as API keys are not written through this API; enter them in **Settings** in the Halo app.

Paths are relative to your Halo base URL, and every request carries the access password. Set `$HALO_URL` and `$HALO_TOKEN` as in the [quickstart](https://hello-halo.cc/docs/en/developers/quickstart.html); base URL, authentication and error conventions are in the [HTTP API overview](https://hello-halo.cc/docs/en/developers/api/).

| Operation | Endpoint |
| --- | --- |
| [List which agent engines are installed and which one is active](#get-api-agent-engine-availability) | `GET /api/agent/engine-availability` |
| [Read what the running agent engine can do](#get-api-agent-engine-capabilities) | `GET /api/agent/engine-capabilities` |
| [Probe one installed MCP server for connectivity and tools](#post-api-agent-probe-mcp) | `POST /api/agent/probe-mcp` |
| [Test every configured MCP server connection](#post-api-agent-test-mcp) | `POST /api/agent/test-mcp` |
| [Switch the model within the current source](#post-api-ai-sources-set-model) | `POST /api/ai-sources/set-model` |
| [Edit a configured model source](#put-api-ai-sources-sources-sourceid) | `PUT /api/ai-sources/sources/:sourceId` |
| [Delete a configured model source](#delete-api-ai-sources-sources-sourceid)  (Irreversible) | `DELETE /api/ai-sources/sources/:sourceId` |
| [Switch to a different configured model source](#post-api-ai-sources-switch-source) | `POST /api/ai-sources/switch-source` |
| [List the sign-in and model providers this build offers](#get-api-auth-providers) | `GET /api/auth/providers` |
| [Read the global configuration](#get-api-config) | `GET /api/config` |
| [List credential fields that failed to decrypt at rest](#get-api-config-credential-failures) | `GET /api/config/credential-failures` |
| [Re-read every model source and return the refreshed config](#post-api-config-refresh-ai-sources) | `POST /api/config/refresh-ai-sources` |
| [List what every known model supports (vision, tools, context)](#get-api-model-capabilities-all) | `GET /api/model-capabilities/all` |
| [Read the shipped capability preset for one model](#get-api-model-capabilities-preset-modelid) | `GET /api/model-capabilities/preset/:modelId` |
| [Resolve a model id to its effective capabilities](#post-api-model-capabilities-resolve) | `POST /api/model-capabilities/resolve` |
| [Read the security policy this build runs under](#get-api-security-policy) | `GET /api/security/policy` |
| [Read the running Halo version](#get-api-system-version) | `GET /api/system/version` |

## List which agent engines are installed and which one is active {#get-api-agent-engine-availability}

`GET /api/agent/engine-availability`  (Assistant)

- degradedFrom is non-null when Halo fell back off the engine the user picked — that is the thing worth telling them about.

**Response**

```ts
{success:true,data:{engines:[{engineId:"anthropic"|"halo"|"codex",available:boolean,version:string,fingerprint:string}],activeEngine,degradedFrom}}
```

**Example**

```bash
curl -s "$HALO_URL/api/agent/engine-availability" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Read what the running agent engine can do {#get-api-agent-engine-capabilities}

`GET /api/agent/engine-capabilities`  (Assistant)

- Describes the agent engine in use: which streaming and tool features it provides natively and which Halo emulates. Always answers; falls back to the active engine's defaults.

**Response**

```ts
{success:true,data:{engineId,displayName,streaming:{text,reasoning,toolInput,toolOutput},tools:{native,synthetic,shellHeuristics},todo:{states,hasActiveForm},subAgent:{...}}}
```

**Example**

```bash
curl -s "$HALO_URL/api/agent/engine-capabilities" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Probe one installed MCP server for connectivity and tools {#post-api-agent-probe-mcp}

`POST /api/agent/probe-mcp`  (Assistant)

- "App is not an MCP server" = that app exists but is not an MCP-type app; probe only applies to those.

**Request body**

```json
{
  "appId": "<appId — a uuid from GET /api/apps>"
}
```

**Response**

```ts
{success:true,result:{status:"connected"|"failed"|"needs-auth",tools?:string[],serverInfo?:{name,version},latencyMs:number}}  // result, not data
```

**Errors**

- 400 if appId is missing.

**Example**

```bash
curl -sX POST "$HALO_URL/api/agent/probe-mcp" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"appId":"<appId — a uuid from GET /api/apps>"}'
```

## Test every configured MCP server connection {#post-api-agent-test-mcp}

`POST /api/agent/test-mcp`  (Assistant)

- Starts a real query against every configured server, so it is slow and it costs tokens. Say so before running it.
- "Test already in progress" = another test is running; wait and retry.
- "No MCP servers configured" comes back with success:true and nothing to report.

**Response**

```ts
{success:true,servers:[{name,status:"connected"|"failed"|"needs-auth"|"pending",tools?:string[],serverInfo?:{name,version},error?}]}  // servers, not data
```

**Example**

```bash
curl -sX POST "$HALO_URL/api/agent/test-mcp" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Switch the model within the current source {#post-api-ai-sources-set-model}

`POST /api/ai-sources/set-model`  (Reversible)  (Assistant)

- Applies to what Halo runs next, including this assistant. Switch back the same way.

**Request body**

```json
{
  "modelId": "deepseek-chat"
}
```

**Response**

```json
{
  "success": true,
  "data": {
    "currentId": "<uuid>",
    "currentModel": "deepseek-chat"
  }
}
```

**Example**

```bash
curl -sX POST "$HALO_URL/api/ai-sources/set-model" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"deepseek-chat"}'
```

## Edit a configured model source {#put-api-ai-sources-sources-sourceid}

`PUT /api/ai-sources/sources/:sourceId`  (Reversible)  (Assistant)

- Merges field by field, so send only what changes. Leave `apiKey` out and the stored key is untouched: renaming a source or pointing it at a different model never needs it.
- Don't send `apiKey` here. Keys are managed in **Settings › AI Model**.

**Path parameters**

| Name | Description |
| --- | --- |
| `sourceId` | Model source id, from [`GET /api/config`](#get-api-config). |

**Request body**

```json
{
  "name": "Work account"
}
```

**Response**

```ts
{"success":true,"data":{...the full sources config, secret fields redacted}}
```

**Example**

```bash
curl -sX PUT "$HALO_URL/api/ai-sources/sources/<sourceId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Work account"}'
```

## Delete a configured model source {#delete-api-ai-sources-sources-sourceid}

`DELETE /api/ai-sources/sources/:sourceId`  (Irreversible)  (Assistant)

::: danger Irreversible
This cannot be undone, and nothing goes to a trash folder. Make sure it is what the user wants before you call it.
If you only need something narrower, use [`POST /api/ai-sources/switch-source`](#post-api-ai-sources-switch-source)
:::

- The stored API key goes with it, and no endpoint here can put one back — only the user can, in Settings &gt; AI Model. Confirm before deleting.

**Path parameters**

| Name | Description |
| --- | --- |
| `sourceId` | Model source id, from [`GET /api/config`](#get-api-config). |

**Response**

```ts
{"success":true,"data":{...the remaining sources config, secret fields redacted}}
```

**Example**

```bash
curl -sX DELETE "$HALO_URL/api/ai-sources/sources/<sourceId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Switch to a different configured model source {#post-api-ai-sources-switch-source}

`POST /api/ai-sources/switch-source`  (Reversible)  (Assistant)

- Picks among sources the user already configured. It cannot create one or change a key.
- Applies to what Halo runs next, including this assistant. Switch back the same way.
- "Source not found" = wrong sourceId; read the configured list from [`GET /api/config`](#get-api-config) first.

**Request body**

```json
{
  "sourceId": "<sourceId — a uuid from GET /api/config>"
}
```

**Response**

```json
{
  "success": true,
  "data": {
    "currentId": "<uuid>",
    "currentModel": "..."
  }
}
```

**Example**

```bash
curl -sX POST "$HALO_URL/api/ai-sources/switch-source" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"<sourceId — a uuid from GET /api/config>"}'
```

## List the sign-in and model providers this build offers {#get-api-auth-providers}

`GET /api/auth/providers`  (Assistant)

- What this build could be configured with, not what the user has configured — read [`GET /api/config`](#get-api-config) for that. On an enterprise build the preset field carries deployment-internal endpoints; do not repeat them back.

**Response**

```json
{
  "success": true,
  "data": [
    {
      "type": "…",
      "displayName": "…",
      "enabled": true,
      "recommended": false,
      "platforms": [
        "darwin"
      ]
    }
  ]
}
```

**Example**

```bash
curl -s "$HALO_URL/api/auth/providers" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Read the global configuration {#get-api-config}

`GET /api/config`  (Assistant)

- Read-only here. The write side is not opened to the assistant. configEpoch -1 means the config file could not be read and data holds the built-in defaults, not what the user configured. productDefaults is read-only build metadata, not user settings: a non-empty user federation.gatewayUrl overrides its gatewayUrl; an empty user value inherits it. A null build gateway with no user override means LAN-only teams.

**Response**

```ts
{"success":true,"data":{...},"configEpoch":0,"productDefaults":{"federation":{"gatewayUrl":null}}}  // secret fields come back as "***"
```

**Example**

```bash
curl -s "$HALO_URL/api/config" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## List credential fields that failed to decrypt at rest {#get-api-config-credential-failures}

`GET /api/config/credential-failures`  (Assistant)

- Path and label only, never ciphertext. Non-empty means the user must re-enter that credential in the Halo app.

**Response**

```json
{
  "success": true,
  "data": [
    {
      "path": "...",
      "label": "..."
    }
  ]
}
```

**Example**

```bash
curl -s "$HALO_URL/api/config/credential-failures" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Re-read every model source and return the refreshed config {#post-api-config-refresh-ai-sources}

`POST /api/config/refresh-ai-sources`  (Assistant)

- Use it when [`GET /api/config`](#get-api-config) looks stale after the user changed a source in the app. It re-reads what is stored; it cannot add or fix a credential.

**Response**

```ts
{"success":true,"data":{...}}  // same masked shape as GET /api/config
```

**Example**

```bash
curl -sX POST "$HALO_URL/api/config/refresh-ai-sources" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## List what every known model supports (vision, tools, context) {#get-api-model-capabilities-all}

`GET /api/model-capabilities/all`  (Assistant)

- Read-only presets. It does not say which model is currently in use.

**Response**

```ts
{"success":true,"data":{"<modelId>":{...capability flags}}}
```

**Example**

```bash
curl -s "$HALO_URL/api/model-capabilities/all" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Read the shipped capability preset for one model {#get-api-model-capabilities-preset-modelid}

`GET /api/model-capabilities/preset/:modelId`  (Assistant)

- An unknown model returns data:null with success:true — not a 404.
- Percent-encode a modelId that contains slashes.

**Path parameters**

| Name | Description |
| --- | --- |
| `modelId` | Model id, as listed in a model source. |

**Response**

```json
{
  "success": true,
  "data": {
    "displayName": "...",
    "provider": "...",
    "contextWindow": 128000,
    "maxOutputTokens": 8192,
    "vision": false,
    "thinking": false
  }
}
```

**Example**

```bash
curl -s "$HALO_URL/api/model-capabilities/preset/<modelId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Resolve a model id to its effective capabilities {#post-api-model-capabilities-resolve}

`POST /api/model-capabilities/resolve`  (Assistant)

- All optional inputs are validated. Catalog data accepts only positive integer contextWindow and maxOutputTokens values within Halo runtime limits; catalogSupportsVision must be a boolean.
- Priority, highest first: user override, then a [1m] model-id suffix (contextWindow only), then an exact preset entry, then catalog data, then a model-family pattern entry, then built-in defaults. A pattern entry is only a family guess and ranks below the provider catalog; an exact entry is curated and ranks above it.
- A context window above 200K is what opts the SDK into extended context — there is no separate switch. A model id ending in [1m] does the same.
- Returns 400 for a missing modelId or malformed capability data.

**Request body**

```json
{
  "modelId": "deepseek-chat",
  "overrides": {
    "deepseek-chat": {
      "contextWindow": 128000
    }
  },
  "catalogCapability": {
    "contextWindow": 128000,
    "maxOutputTokens": 8192
  },
  "catalogSupportsVision": true
}
```

**Response**

```json
{
  "success": true,
  "data": {
    "displayName": "...",
    "provider": "...",
    "contextWindow": 128000,
    "maxOutputTokens": 8192,
    "vision": false,
    "thinking": false
  }
}
```

**Example**

```bash
curl -sX POST "$HALO_URL/api/model-capabilities/resolve" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelId":"deepseek-chat","overrides":{"deepseek-chat":{"contextWindow":128000}},"catalogCapability":{"contextWindow":128000,"maxOutputTokens":8192},"catalogSupportsVision":true}'
```

## Read the security policy this build runs under {#get-api-security-policy}

`GET /api/security/policy`  (Assistant)

- Reports two switches of this build's security policy. `tunnelSafe: true` means Internet Access (the tunnel) is turned off by policy. `browserAllowlistEditable: true` means the AI Browser runs on an allowlist that users may extend.
- Needs no token and always answers.

**Response**

```ts
{"success":true,"data":{"tunnelSafe":boolean,"browserAllowlistEditable":boolean}}
```

**Example**

```bash
curl -s "$HALO_URL/api/security/policy" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## Read the running Halo version {#get-api-system-version}

`GET /api/system/version`  (Assistant)

**Response**

```json
{
  "success": true,
  "data": "2.1.15"
}
```

**Example**

```bash
curl -s "$HALO_URL/api/system/version" \
  -H "Authorization: Bearer $HALO_TOKEN"
```