Skip to content
Core ConceptsCLI ReferenceAPI Reference
CompozyOS RuntimeAPI Reference

Settings

Compozy Settings HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.

Complete a loopback MCP OAuth browser redirect

GET/api/mcp/oauth/callback

Query Parameters

code?string

Authorization code returned by the provider

state*string

Single-use OAuth state

error?string

OAuth error returned by the provider

Response Body

text/html

text/html

application/json

text/html

curl -X GET "https://example.com/api/mcp/oauth/callback?state=string"
"string"

Trigger a daemon restart using the persisted relaunch helper flow

POST/api/settings/actions/restart

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/api/settings/actions/restart"
{  "active_session_count": 0,  "operation_id": "string",  "status": "pending",  "status_url": "string"}

Get the persisted status for one daemon restart operation

GET/api/settings/actions/restart/{operation_id}

Path Parameters

operation_id*string

Restart operation id

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/settings/actions/restart/string"
{  "active_session_count": 0,  "completed_at": "2019-08-24T14:15:22Z",  "failure_reason": "string",  "new_pid": 0,  "old_pid": 0,  "old_socket_path": "string",  "old_started_at": "2019-08-24T14:15:22Z",  "operation_id": "string",  "started_at": "2019-08-24T14:15:22Z",  "status": "pending",  "updated_at": "2019-08-24T14:15:22Z"}

List config apply records for desired and active generation reconciliation

GET/api/settings/apply

Query Parameters

status?string

Filter by apply status

Value in

  • "pending_apply"
  • "applied"
  • "blocked"
  • "failed"
actor?string

Filter by config apply actor

limit?integer

Maximum number of records to return

Formatint32

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/settings/apply"
{  "entries": [    {      "active_config_hash": "string",      "actor": "string",      "applied_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "desired_config_hash": "string",      "diagnostics": [        {          "category": "string",          "code": "string",          "data_freshness": "string",          "doc_url": "string",          "evidence": {            "property1": null,            "property2": null          },          "id": "string",          "message": "string",          "severity": "string",          "suggested_command": "string",          "title": "string"        }      ],      "diff_class": "live",      "generation": 0,      "id": "string",      "lifecycle": "live",      "next_action": "none",      "status": "pending_apply",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

Read the automation settings section

GET/api/settings/automation

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/automation"
{  "available_scopes": [    "global"  ],  "config": {    "default_fire_limit": {      "max": 0,      "window": "string"    },    "enabled": true,    "max_concurrent_jobs": 0,    "timezone": "string"  },  "links": [    {      "label": "string",      "path": "string"    }  ],  "runtime": {    "available": true,    "job_enabled": 0,    "job_total": 0,    "last_synced_at": "2019-08-24T14:15:22Z",    "next_fire": "2019-08-24T14:15:22Z",    "running": true,    "scheduler_running": true,    "trigger_enabled": 0,    "trigger_total": 0  },  "scope": "global",  "section": "general"}

Update the automation settings section

PATCH/api/settings/automation

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/automation" \  -H "Content-Type: application/json" \  -d '{    "config": {      "default_fire_limit": {        "max": 0,        "window": "string"      },      "enabled": true,      "max_concurrent_jobs": 0,      "timezone": "string"    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Read the general settings section

GET/api/settings/general

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/general"
{  "actions": {    "restart": {      "available": true,      "behavior": "applied_now",      "name": "string"    }  },  "available_scopes": [    "global"  ],  "config": {    "daemon": {      "memory_report_interval": "string",      "reload_timeouts": {        "bridges": "string",        "mcp": "string",        "providers": "string"      },      "socket": "string"    },    "defaults": {      "agent": "string",      "provider": "string",      "sandbox": "string"    },    "http": {      "host": "string",      "port": 0    },    "limits": {      "max_concurrent_agents": 0    },    "permissions": {      "mode": "deny-all"    },    "redact": {      "enabled": true    },    "session_timeout": "string"  },  "config_paths": {    "daemon_info": "string",    "global_config": "string",    "global_mcp_sidecar": "string",    "home_dir": "string",    "log_file": "string"  },  "runtime": {    "active_agents": 0,    "active_sessions": 0,    "available": true,    "http_host": "string",    "http_port": 0,    "pid": 0,    "socket": "string",    "started_at": "2019-08-24T14:15:22Z",    "status": "string",    "total_sessions": 0,    "uptime_seconds": 0,    "version": "string"  },  "scope": "global",  "section": "general"}

Update the general settings section

PATCH/api/settings/general

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/general" \  -H "Content-Type: application/json" \  -d '{    "config": {      "daemon": {        "memory_report_interval": "string",        "reload_timeouts": {          "bridges": "string",          "mcp": "string",          "providers": "string"        },        "socket": "string"      },      "defaults": {        "agent": "string"      },      "http": {        "host": "string",        "port": 0      },      "limits": {        "max_concurrent_agents": 0      },      "permissions": {        "mode": "deny-all"      },      "redact": {        "enabled": true      },      "session_timeout": "string"    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

List settings-backed hook declarations

GET/api/settings/hooks

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/hooks"
{  "available_scopes": [    "global"  ],  "collection": "providers",  "hooks": [    {      "declaration": {        "args": [          "string"        ],        "command": "string",        "enabled": true,        "env": {          "property1": "string",          "property2": "string"        },        "event": "session.pre_create",        "executor_kind": "native",        "matcher": {          "acp_event_type": "string",          "agent_name": "string",          "agent_type": "string",          "autonomy": {            "child_session_id": "string",            "coordinator_session_id": "string",            "loop_name": "string",            "loop_run_id": "string",            "node_id": "string",            "parent_session_id": "string",            "participation_channel": "string",            "release_reason": "string",            "root_session_id": "string",            "run_id": "string",            "spawn_role": "string",            "task_id": "string",            "workflow_id": "string"          },          "channel": "string",          "compaction_reason": "string",          "compaction_strategy": "string",          "decision_class": "string",          "direction": "string",          "input_class": "string",          "kind": "string",          "message_delta_type": "string",          "message_role": "string",          "participation_mode": "string",          "participation_source": "string",          "sandbox_backend": "string",          "sandbox_id": "string",          "sandbox_profile": "string",          "session_type": "string",          "surface": "string",          "sync_direction": "string",          "tool_id": "string",          "tool_name": "string",          "tool_read_only": true,          "turn_id": "string",          "work_state": "string",          "workspace_id": "string",          "workspace_root": "string"        },        "metadata": {          "property1": "string",          "property2": "string"        },        "mode": "sync",        "name": "string",        "priority": 0,        "required": true,        "secret_env": {          "property1": "string",          "property2": "string"        },        "timeout": "string"      },      "name": "string",      "source_metadata": {        "available_targets": [          "global-config"        ],        "effective_source": {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        },        "shadowed_sources": [          {            "agent_name": "string",            "kind": "builtin-provider",            "scope": "global",            "workspace_id": "string"          }        ]      }    }  ],  "scope": "global"}

Read the hooks and extensions settings section

GET/api/settings/hooks-extensions

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/hooks-extensions"
{  "available_scopes": [    "global"  ],  "config": {    "marketplace": {      "allow_unverified": true,      "base_url": "string",      "registry": "string"    },    "resources": {      "allowed_kinds": [        "string"      ],      "max_scope": "global",      "operator_write_rate_limit": {        "queue": 0,        "requests": 0,        "window": "string"      },      "snapshot_rate_limit": {        "queue": 0,        "requests": 0,        "window": "string"      }    }  },  "hooks": [    {      "declaration": {        "args": [          "string"        ],        "command": "string",        "enabled": true,        "env": {          "property1": "string",          "property2": "string"        },        "event": "session.pre_create",        "executor_kind": "native",        "matcher": {          "acp_event_type": "string",          "agent_name": "string",          "agent_type": "string",          "autonomy": {            "child_session_id": "string",            "coordinator_session_id": "string",            "loop_name": "string",            "loop_run_id": "string",            "node_id": "string",            "parent_session_id": "string",            "participation_channel": "string",            "release_reason": "string",            "root_session_id": "string",            "run_id": "string",            "spawn_role": "string",            "task_id": "string",            "workflow_id": "string"          },          "channel": "string",          "compaction_reason": "string",          "compaction_strategy": "string",          "decision_class": "string",          "direction": "string",          "input_class": "string",          "kind": "string",          "message_delta_type": "string",          "message_role": "string",          "participation_mode": "string",          "participation_source": "string",          "sandbox_backend": "string",          "sandbox_id": "string",          "sandbox_profile": "string",          "session_type": "string",          "surface": "string",          "sync_direction": "string",          "tool_id": "string",          "tool_name": "string",          "tool_read_only": true,          "turn_id": "string",          "work_state": "string",          "workspace_id": "string",          "workspace_root": "string"        },        "metadata": {          "property1": "string",          "property2": "string"        },        "mode": "sync",        "name": "string",        "priority": 0,        "required": true,        "secret_env": {          "property1": "string",          "property2": "string"        },        "timeout": "string"      },      "name": "string",      "source_metadata": {        "available_targets": [          "global-config"        ],        "effective_source": {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        },        "shadowed_sources": [          {            "agent_name": "string",            "kind": "builtin-provider",            "scope": "global",            "workspace_id": "string"          }        ]      }    }  ],  "installed": [    {      "enabled": true,      "health": "string",      "health_message": "string",      "last_error": "string",      "missing_env": [        "string"      ],      "name": "string",      "requires_env": [        "string"      ],      "state": "string",      "version": "string"    }  ],  "scope": "global",  "section": "general",  "transport_parity": {    "extensions_http": true,    "extensions_uds": true,    "known": true,    "settings_http": true,    "settings_uds": true  }}

Update the hooks and extensions settings section

PATCH/api/settings/hooks-extensions

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/hooks-extensions" \  -H "Content-Type: application/json" \  -d '{    "config": {      "marketplace": {        "allow_unverified": true,        "registry": "string"      },      "resources": {        "operator_write_rate_limit": {          "queue": 0,          "requests": 0,          "window": "string"        },        "snapshot_rate_limit": {          "queue": 0,          "requests": 0,          "window": "string"        }      }    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Delete one settings-backed hook declaration

DELETE/api/settings/hooks/{name}

Path Parameters

name*string

Hook name

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/settings/hooks/string"
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Create or replace one settings-backed hook declaration

PUT/api/settings/hooks/{name}

Path Parameters

name*string

Hook name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/settings/hooks/string" \  -H "Content-Type: application/json" \  -d '{    "declaration": {      "event": "session.pre_create",      "matcher": {},      "name": "string"    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

List settings-backed MCP servers

GET/api/settings/mcp-servers

Query Parameters

scope?string

Select the settings scope

Value in

  • "global"
  • "workspace"
workspace_id?string

Select the workspace id for workspace scope

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/settings/mcp-servers"
{  "available_scopes": [    "global"  ],  "collection": "providers",  "mcp_servers": [    {      "args": [        "string"      ],      "auth": {        "authorization_url": "string",        "client_id": "string",        "client_secret_configured": true,        "issuer_url": "string",        "metadata_url": "string",        "revocation_url": "string",        "scopes": [          "string"        ],        "token_url": "string",        "type": "string"      },      "auth_status": {        "auth_type": "string",        "authorization_url": "string",        "client_id": "string",        "diagnostic": "string",        "expires_at": "2019-08-24T14:15:22Z",        "issuer": "string",        "refreshable": true,        "remote_url": "string",        "revocation_url": "string",        "scope": "string",        "scopes": [          "string"        ],        "server_name": "string",        "status": "string",        "token_present": true,        "updated_at": "2019-08-24T14:15:22Z",        "workspace_id": "string"      },      "catalog_entry": "string",      "catalog_version": "string",      "command": "string",      "env_keys": [        "string"      ],      "name": "string",      "runtime_status": {        "configured": true,        "diagnostic": "string",        "initialized": true,        "probe": "string",        "reason": "string",        "state": "string",        "tool_count": 0      },      "scope": "global",      "secret_env_keys": [        "string"      ],      "source_metadata": {        "available_targets": [          "global-config"        ],        "effective_source": {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        },        "shadowed_sources": [          {            "agent_name": "string",            "kind": "builtin-provider",            "scope": "global",            "workspace_id": "string"          }        ]      },      "transport": "string",      "url": "string",      "workspace_id": "string"    }  ],  "scope": "global",  "workspace_id": "string"}

Install one curated MCP server through settings

POST/api/settings/mcp-servers/install

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/settings/mcp-servers/install" \  -H "Content-Type: application/json" \  -d '{    "entry_id": "string",    "scope": "global",    "values": {}  }'
{  "apply": {    "active_config_hash": "string",    "active_generation": 0,    "agent_name": "string",    "applied": true,    "apply_record_id": "string",    "lifecycle": "live",    "next_action": "none",    "partial_failures": [      {        "diagnostic": {          "category": "string",          "code": "string",          "data_freshness": "string",          "doc_url": "string",          "evidence": {            "property1": null,            "property2": null          },          "id": "string",          "message": "string",          "severity": "string",          "suggested_command": "string",          "title": "string"        },        "subsystem": "string"      }    ],    "restart_required": true,    "restart_scope": "string",    "scope": "global",    "section": "general",    "skipped": true,    "skipped_reason": "string",    "warnings": [      "string"    ],    "workspace_id": "string",    "write_target": "global-config"  },  "mcp_server": {    "args": [      "string"    ],    "auth": {      "authorization_url": "string",      "client_id": "string",      "client_secret_configured": true,      "issuer_url": "string",      "metadata_url": "string",      "revocation_url": "string",      "scopes": [        "string"      ],      "token_url": "string",      "type": "string"    },    "auth_status": {      "auth_type": "string",      "authorization_url": "string",      "client_id": "string",      "diagnostic": "string",      "expires_at": "2019-08-24T14:15:22Z",      "issuer": "string",      "refreshable": true,      "remote_url": "string",      "revocation_url": "string",      "scope": "string",      "scopes": [        "string"      ],      "server_name": "string",      "status": "string",      "token_present": true,      "updated_at": "2019-08-24T14:15:22Z",      "workspace_id": "string"    },    "catalog_entry": "string",    "catalog_version": "string",    "command": "string",    "env_keys": [      "string"    ],    "name": "string",    "runtime_status": {      "configured": true,      "diagnostic": "string",      "initialized": true,      "probe": "string",      "reason": "string",      "state": "string",      "tool_count": 0    },    "scope": "global",    "secret_env_keys": [      "string"    ],    "source_metadata": {      "available_targets": [        "global-config"      ],      "effective_source": {        "agent_name": "string",        "kind": "builtin-provider",        "scope": "global",        "workspace_id": "string"      },      "shadowed_sources": [        {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        }      ]    },    "transport": "string",    "url": "string",    "workspace_id": "string"  },  "next_step": "none",  "warnings": [    {      "category": "string",      "code": "string",      "data_freshness": "string",      "doc_url": "string",      "evidence": {        "property1": null,        "property2": null      },      "id": "string",      "message": "string",      "severity": "string",      "suggested_command": "string",      "title": "string"    }  ]}

Delete one settings-backed MCP server

DELETE/api/settings/mcp-servers/{name}

Path Parameters

name*string

MCP server name

Query Parameters

scope?string

Select the settings scope

Value in

  • "global"
  • "workspace"
workspace_id?string

Select the workspace id for workspace scope

target?string

Select the persistence target

Value in

  • "auto"
  • "config"
  • "sidecar"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/settings/mcp-servers/string"
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Create or replace one settings-backed MCP server

PUT/api/settings/mcp-servers/{name}

Path Parameters

name*string

MCP server name

Query Parameters

scope?string

Select the settings scope

Value in

  • "global"
  • "workspace"
workspace_id?string

Select the workspace id for workspace scope

target?string

Select the persistence target

Value in

  • "auto"
  • "config"
  • "sidecar"

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/settings/mcp-servers/string" \  -H "Content-Type: application/json" \  -d '{    "server": {      "name": "string"    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Begin daemon-mediated OAuth for one MCP server

POST/api/settings/mcp-servers/{name}/auth/begin

Path Parameters

name*string

Configured MCP server name

Query Parameters

scope*string

Exact MCP settings scope

Value in

  • "global"
  • "workspace"
workspace_id?string

Required when scope is workspace

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/settings/mcp-servers/string/auth/begin?scope=global" \  -H "Content-Type: application/json" \  -d '{    "mode": "automatic"  }'
{  "authorization_url": "string",  "callback_url": "string",  "expires_at": "2019-08-24T14:15:22Z",  "manual_supported": true,  "state": "string"}

Complete daemon-mediated OAuth for one MCP server

POST/api/settings/mcp-servers/{name}/auth/exchange

Path Parameters

name*string

Configured MCP server name

Query Parameters

scope*string

Exact MCP settings scope

Value in

  • "global"
  • "workspace"
workspace_id?string

Required when scope is workspace

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/settings/mcp-servers/string/auth/exchange?scope=global" \  -H "Content-Type: application/json" \  -d '{    "code": "string"  }'
{  "auth_type": "string",  "authorization_url": "string",  "client_id": "string",  "diagnostic": "string",  "expires_at": "2019-08-24T14:15:22Z",  "issuer": "string",  "refreshable": true,  "remote_url": "string",  "revocation_url": "string",  "scope": "string",  "scopes": [    "string"  ],  "server_name": "string",  "status": "string",  "token_present": true,  "updated_at": "2019-08-24T14:15:22Z",  "workspace_id": "string"}

Log out one scoped MCP server

POST/api/settings/mcp-servers/{name}/auth/logout

Path Parameters

name*string

Configured MCP server name

Query Parameters

scope*string

Exact MCP settings scope

Value in

  • "global"
  • "workspace"
workspace_id?string

Required when scope is workspace

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/settings/mcp-servers/string/auth/logout?scope=global"
{  "auth_type": "string",  "authorization_url": "string",  "client_id": "string",  "diagnostic": "string",  "expires_at": "2019-08-24T14:15:22Z",  "issuer": "string",  "refreshable": true,  "remote_url": "string",  "revocation_url": "string",  "scope": "string",  "scopes": [    "string"  ],  "server_name": "string",  "status": "string",  "token_present": true,  "updated_at": "2019-08-24T14:15:22Z",  "workspace_id": "string"}

Read the memory settings section

GET/api/settings/memory

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/memory"
{  "actions": {    "consolidate": {      "available": true,      "behavior": "applied_now",      "name": "string"    }  },  "available_scopes": [    "global"  ],  "config": {    "controller": {      "default_op_on_fail": "string",      "max_latency": "string",      "mode": "string",      "policy": {        "allow_origins": [          "string"        ],        "max_content_chars": 0,        "max_writes_per_min": 0      }    },    "daily": {      "archive_path": "string",      "cold_archive_days": 0,      "dreaming_window": 0,      "hard_delete_days": 0,      "max_archive_bytes": 0,      "max_bytes": 0,      "max_lines": 0,      "rotate_format": "string",      "sweep_hour": 0    },    "decisions": {      "keep_audit_summary": true,      "max_post_content_bytes": 0,      "prune_after_applied_days": 0    },    "dream": {      "check_interval": "string",      "debounce": "string",      "gates": {        "min_recall_count": 0,        "min_score": 0.1,        "min_unpromoted": 0      },      "min_hours": 0.1,      "min_sessions": 0,      "prompt_version": "string",      "scoring": {        "recency_half_life_days": 0,        "weights": {          "frequency": 0.1,          "freshness": 0.1,          "recency": 0.1,          "relevance": 0.1        }      }    },    "enabled": true,    "extractor": {      "deadline": "string",      "dlq_path": "string",      "inbox_path": "string",      "mode": "string",      "queue": {        "capacity": 0,        "coalesce_max": 0      },      "sandbox_inbox_only": true,      "throttle_turns": 0    },    "file": {      "max_bytes": 0,      "max_lines": 0    },    "global_dir": "string",    "provider": {      "cooldown": "string",      "failure_threshold": 0,      "name": "string",      "timeout": "string"    },    "recall": {      "freshness": {        "banner_after_days": 0      },      "fusion": "string",      "include_already_surfaced": true,      "include_system": true,      "raw_candidates": 0,      "signals": {        "metrics_enabled": true,        "queue_capacity": 0,        "worker_retry_max": 0      },      "top_k": 0,      "weights": {        "bm25_trigram": 0.1,        "bm25_unicode": 0.1,        "recall_signal": 0.1,        "recency": 0.1      }    },    "session": {      "cold_archive_days": 0,      "events_purge_grace": "string",      "hard_delete_days": 0,      "ledger_format": "string",      "ledger_root": "string",      "max_archive_bytes": 0,      "unbound_partition": "string"    },    "workspace": {      "auto_create": true,      "toml_path": "string"    }  },  "health": {    "available": true,    "dream_enabled": true,    "file_count": 0,    "last_consolidated_at": "2019-08-24T14:15:22Z"  },  "scope": "global",  "section": "general"}

Update the memory settings section

PATCH/api/settings/memory

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/memory" \  -H "Content-Type: application/json" \  -d '{    "config": {      "controller": {        "default_op_on_fail": "string",        "max_latency": "string",        "mode": "string",        "policy": {          "allow_origins": [            "string"          ],          "max_content_chars": 0,          "max_writes_per_min": 0        }      },      "daily": {        "archive_path": "string",        "cold_archive_days": 0,        "dreaming_window": 0,        "hard_delete_days": 0,        "max_archive_bytes": 0,        "max_bytes": 0,        "max_lines": 0,        "rotate_format": "string",        "sweep_hour": 0      },      "decisions": {        "keep_audit_summary": true,        "max_post_content_bytes": 0,        "prune_after_applied_days": 0      },      "dream": {        "check_interval": "string",        "debounce": "string",        "gates": {          "min_recall_count": 0,          "min_score": 0.1,          "min_unpromoted": 0        },        "min_hours": 0.1,        "min_sessions": 0,        "prompt_version": "string",        "scoring": {          "recency_half_life_days": 0,          "weights": {            "frequency": 0.1,            "freshness": 0.1,            "recency": 0.1,            "relevance": 0.1          }        }      },      "enabled": true,      "extractor": {        "deadline": "string",        "dlq_path": "string",        "inbox_path": "string",        "mode": "string",        "queue": {          "capacity": 0,          "coalesce_max": 0        },        "sandbox_inbox_only": true,        "throttle_turns": 0      },      "file": {        "max_bytes": 0,        "max_lines": 0      },      "provider": {        "cooldown": "string",        "failure_threshold": 0,        "name": "string",        "timeout": "string"      },      "recall": {        "freshness": {          "banner_after_days": 0        },        "fusion": "string",        "include_already_surfaced": true,        "include_system": true,        "raw_candidates": 0,        "signals": {          "metrics_enabled": true,          "queue_capacity": 0,          "worker_retry_max": 0        },        "top_k": 0,        "weights": {          "bm25_trigram": 0.1,          "bm25_unicode": 0.1,          "recall_signal": 0.1,          "recency": 0.1        }      },      "session": {        "cold_archive_days": 0,        "events_purge_grace": "string",        "hard_delete_days": 0,        "ledger_format": "string",        "ledger_root": "string",        "max_archive_bytes": 0,        "unbound_partition": "string"      },      "workspace": {        "auto_create": true,        "toml_path": "string"      }    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Read the network settings section

GET/api/settings/network

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/network"
{  "available_scopes": [    "global"  ],  "config": {    "enabled": true,    "live": {      "defaults": {        "coalesce_window": "string",        "max_input_tokens": 0,        "max_output_tokens": 0,        "max_total_wall_time": "string",        "max_wake_depth": 0,        "max_wake_wall_time": "string",        "max_wakes": 0      },      "limits": {        "max_coalesce_window": "string",        "max_input_tokens": 0,        "max_output_tokens": 0,        "max_total_wall_time": "string",        "max_wake_depth": 0,        "max_wake_wall_time": "string",        "max_wakes": 0,        "min_coalesce_window": "string"      }    },    "max_replay_age": 0  },  "links": [    {      "label": "string",      "path": "string"    }  ],  "runtime": {    "available": true,    "channels": 0,    "enabled": true,    "local_peers": 0,    "messages_delivered": 0,    "messages_received": 0,    "messages_rejected": 0,    "status": "string"  },  "scope": "global",  "section": "general"}

Update the network settings section

PATCH/api/settings/network

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/network" \  -H "Content-Type: application/json" \  -d '{    "config": {      "enabled": true,      "live": {        "defaults": {          "coalesce_window": "string",          "max_input_tokens": 0,          "max_output_tokens": 0,          "max_total_wall_time": "string",          "max_wake_depth": 0,          "max_wake_wall_time": "string",          "max_wakes": 0        },        "limits": {          "max_coalesce_window": "string",          "max_input_tokens": 0,          "max_output_tokens": 0,          "max_total_wall_time": "string",          "max_wake_depth": 0,          "max_wake_wall_time": "string",          "max_wakes": 0,          "min_coalesce_window": "string"        }      },      "max_replay_age": 0    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Read the observability settings section

GET/api/settings/observability

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/observability"
{  "available_scopes": [    "global"  ],  "config": {    "enabled": true,    "max_global_bytes": 0,    "retention_days": 0,    "transcripts": {      "enabled": true,      "max_bytes_per_session": 0,      "segment_bytes": 0    }  },  "log_tail": {    "available": true,    "stream_url": "string",    "transport": "sse"  },  "runtime": {    "active_agents": 0,    "active_sessions": 0,    "available": true,    "global_db_size_bytes": 0,    "session_db_size_bytes": 0,    "status": "string",    "uptime_seconds": 0  },  "scope": "global",  "section": "general"}

Update the observability settings section

PATCH/api/settings/observability

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/observability" \  -H "Content-Type: application/json" \  -d '{    "config": {      "enabled": true,      "max_global_bytes": 0,      "retention_days": 0,      "transcripts": {        "enabled": true,        "max_bytes_per_session": 0,        "segment_bytes": 0      }    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Stream daemon log output for the observability settings screen

GET/api/settings/observability/log-tail

Response Body

application/json

curl -X GET "https://example.com/api/settings/observability/log-tail"
Empty

List settings-backed providers

GET/api/settings/providers

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/providers"
{  "available_scopes": [    "global"  ],  "collection": "providers",  "providers": [    {      "auth_status": {        "code": "string",        "env_policy": "string",        "home_policy": "string",        "login_command": "string",        "login_env": [          "string"        ],        "message": "string",        "mode": "string",        "native_cli": {          "command": "string",          "error": "string",          "path": "string",          "present": true,          "source": "string"        },        "state": "string",        "status_command": "string"      },      "command_available": true,      "credentials": [        {          "kind": "string",          "name": "string",          "present": true,          "required": true,          "secret_ref": "string",          "source": "string",          "target_env": "string"        }      ],      "default": true,      "fallback": {        "settings": {          "auth_login_command": "string",          "auth_mode": "string",          "auth_status_command": "string",          "base_url": "string",          "command": "string",          "credential_slots": [            {              "kind": "string",              "name": "string",              "required": true,              "secret_ref": "string",              "target_env": "string"            }          ],          "display_name": "string",          "env_policy": "string",          "harness": "string",          "home_policy": "string",          "models": {            "curated": [              {                "context_window": 0,                "cost_cache_read_per_million": 0,                "cost_cache_write_per_million": 0,                "cost_input_per_million": 0,                "cost_output_per_million": 0,                "cost_reasoning_per_million": 0,                "default_reasoning_effort": "none",                "deprecated": true,                "display_name": "string",                "featured": true,                "hidden": true,                "id": "string",                "max_input_tokens": 0,                "max_output_tokens": 0,                "reasoning_efforts": [                  "none"                ],                "release_date": "string",                "supports_reasoning": true,                "supports_tools": true              }            ],            "default": "string",            "discovery": {              "command": "string",              "enabled": true,              "endpoint": "string",              "timeout": "string"            },            "reasoning": {              "apply": "string"            }          },          "runtime_provider": "string",          "transport": "string"        },        "source": {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        }      },      "name": "string",      "settings": {        "auth_login_command": "string",        "auth_mode": "string",        "auth_status_command": "string",        "base_url": "string",        "command": "string",        "credential_slots": [          {            "kind": "string",            "name": "string",            "required": true,            "secret_ref": "string",            "target_env": "string"          }        ],        "display_name": "string",        "env_policy": "string",        "harness": "string",        "home_policy": "string",        "models": {          "curated": [            {              "context_window": 0,              "cost_cache_read_per_million": 0,              "cost_cache_write_per_million": 0,              "cost_input_per_million": 0,              "cost_output_per_million": 0,              "cost_reasoning_per_million": 0,              "default_reasoning_effort": "none",              "deprecated": true,              "display_name": "string",              "featured": true,              "hidden": true,              "id": "string",              "max_input_tokens": 0,              "max_output_tokens": 0,              "reasoning_efforts": [                "none"              ],              "release_date": "string",              "supports_reasoning": true,              "supports_tools": true            }          ],          "default": "string",          "discovery": {            "command": "string",            "enabled": true,            "endpoint": "string",            "timeout": "string"          },          "reasoning": {            "apply": "string"          }        },        "runtime_provider": "string",        "transport": "string"      },      "source_metadata": {        "available_targets": [          "global-config"        ],        "effective_source": {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        },        "shadowed_sources": [          {            "agent_name": "string",            "kind": "builtin-provider",            "scope": "global",            "workspace_id": "string"          }        ]      }    }  ],  "scope": "global"}

Read one settings-backed provider

GET/api/settings/providers/{name}

Path Parameters

name*string

Provider name

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/settings/providers/string"
{  "provider": {    "auth_status": {      "code": "string",      "env_policy": "string",      "home_policy": "string",      "login_command": "string",      "login_env": [        "string"      ],      "message": "string",      "mode": "string",      "native_cli": {        "command": "string",        "error": "string",        "path": "string",        "present": true,        "source": "string"      },      "state": "string",      "status_command": "string"    },    "command_available": true,    "credentials": [      {        "kind": "string",        "name": "string",        "present": true,        "required": true,        "secret_ref": "string",        "source": "string",        "target_env": "string"      }    ],    "default": true,    "fallback": {      "settings": {        "auth_login_command": "string",        "auth_mode": "string",        "auth_status_command": "string",        "base_url": "string",        "command": "string",        "credential_slots": [          {            "kind": "string",            "name": "string",            "required": true,            "secret_ref": "string",            "target_env": "string"          }        ],        "display_name": "string",        "env_policy": "string",        "harness": "string",        "home_policy": "string",        "models": {          "curated": [            {              "context_window": 0,              "cost_cache_read_per_million": 0,              "cost_cache_write_per_million": 0,              "cost_input_per_million": 0,              "cost_output_per_million": 0,              "cost_reasoning_per_million": 0,              "default_reasoning_effort": "none",              "deprecated": true,              "display_name": "string",              "featured": true,              "hidden": true,              "id": "string",              "max_input_tokens": 0,              "max_output_tokens": 0,              "reasoning_efforts": [                "none"              ],              "release_date": "string",              "supports_reasoning": true,              "supports_tools": true            }          ],          "default": "string",          "discovery": {            "command": "string",            "enabled": true,            "endpoint": "string",            "timeout": "string"          },          "reasoning": {            "apply": "string"          }        },        "runtime_provider": "string",        "transport": "string"      },      "source": {        "agent_name": "string",        "kind": "builtin-provider",        "scope": "global",        "workspace_id": "string"      }    },    "name": "string",    "settings": {      "auth_login_command": "string",      "auth_mode": "string",      "auth_status_command": "string",      "base_url": "string",      "command": "string",      "credential_slots": [        {          "kind": "string",          "name": "string",          "required": true,          "secret_ref": "string",          "target_env": "string"        }      ],      "display_name": "string",      "env_policy": "string",      "harness": "string",      "home_policy": "string",      "models": {        "curated": [          {            "context_window": 0,            "cost_cache_read_per_million": 0,            "cost_cache_write_per_million": 0,            "cost_input_per_million": 0,            "cost_output_per_million": 0,            "cost_reasoning_per_million": 0,            "default_reasoning_effort": "none",            "deprecated": true,            "display_name": "string",            "featured": true,            "hidden": true,            "id": "string",            "max_input_tokens": 0,            "max_output_tokens": 0,            "reasoning_efforts": [              "none"            ],            "release_date": "string",            "supports_reasoning": true,            "supports_tools": true          }        ],        "default": "string",        "discovery": {          "command": "string",          "enabled": true,          "endpoint": "string",          "timeout": "string"        },        "reasoning": {          "apply": "string"        }      },      "runtime_provider": "string",      "transport": "string"    },    "source_metadata": {      "available_targets": [        "global-config"      ],      "effective_source": {        "agent_name": "string",        "kind": "builtin-provider",        "scope": "global",        "workspace_id": "string"      },      "shadowed_sources": [        {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        }      ]    }  }}

Delete one settings-backed provider overlay

DELETE/api/settings/providers/{name}

Path Parameters

name*string

Provider name

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/settings/providers/string"
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Create or replace one settings-backed provider overlay

PUT/api/settings/providers/{name}

Path Parameters

name*string

Provider name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/settings/providers/string" \  -H "Content-Type: application/json" \  -d '{    "settings": {}  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Reconcile config.toml with the daemon active generation

POST/api/settings/reload

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/settings/reload"
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Read the background-role routing settings section

GET/api/settings/roles

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/roles"
{  "available_scopes": [    "global"  ],  "config": {    "auto_title": {      "agent": "string",      "enabled": true,      "fallback_chain": [        {          "model": "string",          "provider": "string",          "reasoning_effort": "string"        }      ],      "model": "string",      "provider": "string",      "reasoning_effort": "string"    },    "checkpoint_summary": {      "agent": "string",      "enabled": true,      "fallback_chain": [        {          "model": "string",          "provider": "string",          "reasoning_effort": "string"        }      ],      "model": "string",      "provider": "string",      "reasoning_effort": "string"    },    "coordinator": {      "agent": "string",      "enabled": true,      "fallback_chain": [        {          "model": "string",          "provider": "string",          "reasoning_effort": "string"        }      ],      "max_active_sessions_per_workspace": 0,      "max_children": 0,      "model": "string",      "provider": "string",      "reasoning_effort": "string",      "ttl": "string"    },    "dream": {      "agent": "string",      "enabled": true,      "fallback_chain": [        {          "model": "string",          "provider": "string",          "reasoning_effort": "string"        }      ],      "model": "string",      "provider": "string",      "reasoning_effort": "string"    },    "memory_controller": {      "enabled": true,      "fallback_chain": [        {          "model": "string",          "provider": "string",          "reasoning_effort": "string"        }      ],      "max_tokens_out": 0,      "model": "string",      "prompt_version": "string",      "provider": "string",      "reasoning_effort": "string",      "timeout": "string",      "top_k": 0    },    "memory_extractor": {      "agent": "string",      "enabled": true,      "fallback_chain": [        {          "model": "string",          "provider": "string",          "reasoning_effort": "string"        }      ],      "model": "string",      "provider": "string",      "reasoning_effort": "string"    }  },  "scope": "global",  "section": "general"}

Update the background-role routing settings section

PATCH/api/settings/roles

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/roles" \  -H "Content-Type: application/json" \  -d '{    "config": {      "auto_title": {        "agent": "string",        "enabled": true,        "fallback_chain": [          {            "model": "string",            "provider": "string",            "reasoning_effort": "string"          }        ],        "model": "string",        "provider": "string",        "reasoning_effort": "string"      },      "checkpoint_summary": {        "agent": "string",        "enabled": true,        "fallback_chain": [          {            "model": "string",            "provider": "string",            "reasoning_effort": "string"          }        ],        "model": "string",        "provider": "string",        "reasoning_effort": "string"      },      "coordinator": {        "agent": "string",        "enabled": true,        "fallback_chain": [          {            "model": "string",            "provider": "string",            "reasoning_effort": "string"          }        ],        "max_active_sessions_per_workspace": 0,        "max_children": 0,        "model": "string",        "provider": "string",        "reasoning_effort": "string",        "ttl": "string"      },      "dream": {        "agent": "string",        "enabled": true,        "fallback_chain": [          {            "model": "string",            "provider": "string",            "reasoning_effort": "string"          }        ],        "model": "string",        "provider": "string",        "reasoning_effort": "string"      },      "memory_controller": {        "enabled": true,        "fallback_chain": [          {            "model": "string",            "provider": "string",            "reasoning_effort": "string"          }        ],        "max_tokens_out": 0,        "model": "string",        "prompt_version": "string",        "provider": "string",        "reasoning_effort": "string",        "timeout": "string",        "top_k": 0      },      "memory_extractor": {        "agent": "string",        "enabled": true,        "fallback_chain": [          {            "model": "string",            "provider": "string",            "reasoning_effort": "string"          }        ],        "model": "string",        "provider": "string",        "reasoning_effort": "string"      }    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

List settings-backed execution sandboxes

GET/api/settings/sandboxes

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/sandboxes"
{  "available_scopes": [    "global"  ],  "collection": "providers",  "sandboxes": [    {      "name": "string",      "profile": {        "backend": "string",        "daytona": {          "api_url": "string",          "auto_archive": "string",          "auto_stop": "string",          "class": "string",          "image": "string",          "snapshot": "string",          "target": "string"        },        "env": {          "property1": "string",          "property2": "string"        },        "network": {          "allow_list": [            "string"          ],          "allow_outbound": true,          "allow_public_ingress": true,          "deny_list": [            "string"          ],          "required": true        },        "persistence": "string",        "runtime_root": "string",        "secret_env": {          "property1": "string",          "property2": "string"        },        "sync_mode": "string"      },      "source_metadata": {        "available_targets": [          "global-config"        ],        "effective_source": {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        },        "shadowed_sources": [          {            "agent_name": "string",            "kind": "builtin-provider",            "scope": "global",            "workspace_id": "string"          }        ]      },      "workspace_usage_count": 0    }  ],  "scope": "global"}

Read one settings-backed execution sandbox

GET/api/settings/sandboxes/{name}

Path Parameters

name*string

Sandbox name

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/settings/sandboxes/string"
{  "sandbox": {    "name": "string",    "profile": {      "backend": "string",      "daytona": {        "api_url": "string",        "auto_archive": "string",        "auto_stop": "string",        "class": "string",        "image": "string",        "snapshot": "string",        "target": "string"      },      "env": {        "property1": "string",        "property2": "string"      },      "network": {        "allow_list": [          "string"        ],        "allow_outbound": true,        "allow_public_ingress": true,        "deny_list": [          "string"        ],        "required": true      },      "persistence": "string",      "runtime_root": "string",      "secret_env": {        "property1": "string",        "property2": "string"      },      "sync_mode": "string"    },    "source_metadata": {      "available_targets": [        "global-config"      ],      "effective_source": {        "agent_name": "string",        "kind": "builtin-provider",        "scope": "global",        "workspace_id": "string"      },      "shadowed_sources": [        {          "agent_name": "string",          "kind": "builtin-provider",          "scope": "global",          "workspace_id": "string"        }      ]    },    "workspace_usage_count": 0  }}

Delete one settings-backed execution sandbox overlay

DELETE/api/settings/sandboxes/{name}

Path Parameters

name*string

Sandbox name

Response Body

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/api/settings/sandboxes/string"
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Create or replace one settings-backed execution sandbox

PUT/api/settings/sandboxes/{name}

Path Parameters

name*string

Sandbox name

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/api/settings/sandboxes/string" \  -H "Content-Type: application/json" \  -d '{    "profile": {      "backend": "string"    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Read the skills settings section

GET/api/settings/skills

Query Parameters

scope?string

Select the settings scope

Value in

  • "global"
  • "agent"
workspace_id?string

Optional workspace id for agent resolution context

agent_name?string

Agent name when scope=agent

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/settings/skills"
{  "agent_name": "string",  "available_scopes": [    "global"  ],  "config": {    "allowed_marketplace_hooks": [      "string"    ],    "allowed_marketplace_mcp": [      "string"    ],    "disabled_skills": [      "string"    ],    "enabled": true,    "marketplace": {      "base_url": "string",      "registry": "string"    },    "poll_interval": "string"  },  "diagnostics": [    {      "activation_reasons": [        {          "code": "platform_mismatch",          "gate": "string",          "message": "string",          "missing": [            "string"          ]        }      ],      "failure": {        "actual_hash": "string",        "code": "string",        "expected_hash": "string",        "message": "string"      },      "name": "string",      "path": "string",      "source": "string",      "state": "valid",      "verification_status": "passed",      "warnings": [        {          "message": "string",          "pattern": "string",          "severity": "string"        }      ],      "winning_path": "string",      "winning_source": "string"    }  ],  "disabled_count": 0,  "discovered_count": 0,  "links": [    {      "label": "string",      "path": "string"    }  ],  "runtime_available": true,  "scope": "global",  "section": "general",  "workspace_id": "string"}

Update the skills settings section

PATCH/api/settings/skills

Query Parameters

scope?string

Select the settings scope

Value in

  • "global"
  • "agent"
workspace_id?string

Optional workspace id for agent resolution context

agent_name?string

Agent name when scope=agent

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/skills" \  -H "Content-Type: application/json" \  -d '{    "config": {      "enabled": true,      "marketplace": {        "registry": "string"      },      "poll_interval": "string"    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Read the current CompozyOS software update status

GET/api/settings/update

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/settings/update"
{  "available": true,  "checked_at": "2019-08-24T14:15:22Z",  "current_version": "string",  "install_method": "string",  "last_error": "string",  "latest_version": "string",  "managed": true,  "recommendation": "string",  "release_url": "string",  "status": "current",  "supported": true}

Read the window-manager settings section

GET/api/settings/window-manager

Response Body

application/json

application/json

curl -X GET "https://example.com/api/settings/window-manager"
{  "available_scopes": [    "global"  ],  "config": {    "bindings": {      "bottom_center": "none",      "top_center": "none"    },    "desktop_transition": "slide",    "drag_away_policy": "window",    "focus_follows_pointer": true,    "focus_policy": "click_directional",    "focus_wrap": true,    "gaps": {      "bottom": 0,      "inner": 0,      "left": 0,      "right": 0,      "top": 0    },    "group_move_modifier": "alt",    "history_limit": 0,    "new_window_policy": "floating",    "raise_on_focus": true,    "shortcuts": {      "property1": "string",      "property2": "string"    },    "small_viewport_policy": "stack",    "snap": {      "corner_reach": 0,      "edge_band": 0,      "exit_slack": 0,      "repeat_ratios": [        0.1      ]    },    "swap_modifier": "alt"  },  "scope": "global",  "section": "general"}

Update the window-manager settings section

PATCH/api/settings/window-manager

Request Body

application/json

JSON request body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/api/settings/window-manager" \  -H "Content-Type: application/json" \  -d '{    "config": {      "bindings": {        "bottom_center": "none",        "top_center": "none"      },      "desktop_transition": "slide",      "drag_away_policy": "window",      "focus_follows_pointer": true,      "focus_policy": "click_directional",      "focus_wrap": true,      "gaps": {        "bottom": 0,        "inner": 0,        "left": 0,        "right": 0,        "top": 0      },      "group_move_modifier": "alt",      "history_limit": 0,      "new_window_policy": "floating",      "raise_on_focus": true,      "shortcuts": {        "property1": "string",        "property2": "string"      },      "small_viewport_policy": "stack",      "snap": {        "corner_reach": 0,        "edge_band": 0,        "exit_slack": 0,        "repeat_ratios": [          0.1        ]      },      "swap_modifier": "alt"    }  }'
{  "active_config_hash": "string",  "active_generation": 0,  "agent_name": "string",  "applied": true,  "apply_record_id": "string",  "lifecycle": "live",  "next_action": "none",  "partial_failures": [    {      "diagnostic": {        "category": "string",        "code": "string",        "data_freshness": "string",        "doc_url": "string",        "evidence": {          "property1": null,          "property2": null        },        "id": "string",        "message": "string",        "severity": "string",        "suggested_command": "string",        "title": "string"      },      "subsystem": "string"    }  ],  "restart_required": true,  "restart_scope": "string",  "scope": "global",  "section": "general",  "skipped": true,  "skipped_reason": "string",  "warnings": [    "string"  ],  "workspace_id": "string",  "write_target": "global-config"}

Logs

Compozy Logs HTTP endpoints.

Support

Compozy Support HTTP endpoints.