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; base URL, authentication and error conventions are in the HTTP API overview.

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

List which agent engines are installed and which one is active

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

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

Example

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

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

Example

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 Assistant

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

Request body

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

Response

{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

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

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

Example

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 Reversible Assistant

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

Request body

{
  "modelId": "deepseek-chat"
}

Response

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

Example

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 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.

Request body

{
  "name": "Work account"
}

Response

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

Example

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 Irreversible Assistant

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

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

Path parameters

Name	Description
sourceId	Model source id, from GET /api/config.

Response

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

Example

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 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 first.

Request body

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

Response

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

Example

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 Assistant

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

Response

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

Example

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

Read the global configuration

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

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

Example

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 Assistant

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

Response

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

Example

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 Assistant

• Use it when 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

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

Example

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 Assistant

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

Response

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

Example

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

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

Example

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

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

Response

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

Example

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

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

Example

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

Read the running Halo version

GET /api/system/version Assistant

Response

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

Example

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