Skip to content
Core ConceptsCLI ReferenceAPI Reference
AGH RuntimeAPI Reference

Settings

AGH Settings HTTP endpoints.

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

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"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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"
    }
  ]
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": {
      "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"
    },
    "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"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": {        "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"      },      "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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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",
        "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",
            "coordination_channel_id": "string",
            "coordinator_session_id": "string",
            "parent_session_id": "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",
          "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"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": {
      "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",
        "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",
            "coordination_channel_id": "string",
            "coordinator_session_id": "string",
            "parent_session_id": "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",
          "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
  }
}
{
  "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"
  },
  "error": "string"
}
Empty

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": {        "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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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_ref": "string",
        "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",
        "scopes": [
          "string"
        ],
        "server_name": "string",
        "status": "string",
        "token_present": true,
        "updated_at": "2019-08-24T14:15:22Z"
      },
      "command": "string",
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "name": "string",
      "runtime_status": {
        "configured": true,
        "diagnostic": "string",
        "initialized": true,
        "probe": "string",
        "reason": "string",
        "state": "string",
        "tool_count": 0
      },
      "scope": "global",
      "secret_env": {
        "property1": "string",
        "property2": "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"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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",
      "llm": {
        "enabled": true,
        "max_tokens_out": 0,
        "model": "string",
        "prompt_version": "string",
        "timeout": "string",
        "top_k": 0
      },
      "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": {
      "agent": "string",
      "check_interval": "string",
      "debounce": "string",
      "enabled": true,
      "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",
      "enabled": true,
      "inbox_path": "string",
      "mode": "string",
      "model": "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"
}
{
  "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"
  },
  "error": "string"
}
Empty

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",        "llm": {          "enabled": true,          "max_tokens_out": 0,          "model": "string",          "prompt_version": "string",          "timeout": "string",          "top_k": 0        },        "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": {        "agent": "string",        "check_interval": "string",        "debounce": "string",        "enabled": true,        "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",        "enabled": true,        "inbox_path": "string",        "mode": "string",        "model": "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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": {
    "default_channel": "string",
    "enabled": true,
    "greet_interval": 0,
    "max_payload": 0,
    "max_queue_depth": 0,
    "max_replay_age": 0,
    "port": 0
  },
  "links": [
    {
      "label": "string",
      "path": "string"
    }
  ],
  "runtime": {
    "available": true,
    "channels": 0,
    "delivery_workers": 0,
    "enabled": true,
    "listener_host": "string",
    "listener_port": 0,
    "local_peers": 0,
    "queued_messages": 0,
    "queued_sessions": 0,
    "remote_peers": 0,
    "status": "string"
  },
  "scope": "global",
  "section": "general"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": {      "default_channel": "string",      "enabled": true,      "greet_interval": 0,      "max_payload": 0,      "max_queue_depth": 0,      "max_replay_age": 0,      "port": 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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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
{
  "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"
  },
  "error": "string"
}
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_input_per_million": 0,
                "cost_output_per_million": 0,
                "default_reasoning_effort": "string",
                "display_name": "string",
                "id": "string",
                "max_input_tokens": 0,
                "max_output_tokens": 0,
                "reasoning_efforts": [
                  "string"
                ],
                "supports_reasoning": true,
                "supports_tools": true
              }
            ],
            "default": "string",
            "discovery": {
              "command": "string",
              "enabled": true,
              "endpoint": "string",
              "timeout": "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_input_per_million": 0,
              "cost_output_per_million": 0,
              "default_reasoning_effort": "string",
              "display_name": "string",
              "id": "string",
              "max_input_tokens": 0,
              "max_output_tokens": 0,
              "reasoning_efforts": [
                "string"
              ],
              "supports_reasoning": true,
              "supports_tools": true
            }
          ],
          "default": "string",
          "discovery": {
            "command": "string",
            "enabled": true,
            "endpoint": "string",
            "timeout": "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"
}
{
  "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"
  },
  "error": "string"
}
Empty

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_input_per_million": 0,
              "cost_output_per_million": 0,
              "default_reasoning_effort": "string",
              "display_name": "string",
              "id": "string",
              "max_input_tokens": 0,
              "max_output_tokens": 0,
              "reasoning_efforts": [
                "string"
              ],
              "supports_reasoning": true,
              "supports_tools": true
            }
          ],
          "default": "string",
          "discovery": {
            "command": "string",
            "enabled": true,
            "endpoint": "string",
            "timeout": "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_input_per_million": 0,
            "cost_output_per_million": 0,
            "default_reasoning_effort": "string",
            "display_name": "string",
            "id": "string",
            "max_input_tokens": 0,
            "max_output_tokens": 0,
            "reasoning_efforts": [
              "string"
            ],
            "supports_reasoning": true,
            "supports_tools": true
          }
        ],
        "default": "string",
        "discovery": {
          "command": "string",
          "enabled": true,
          "endpoint": "string",
          "timeout": "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"
        }
      ]
    }
  }
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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"
}
{
  "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"
  },
  "error": "string"
}
Empty

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
  }
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": [
    {
      "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"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

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": "string",
  "skipped": true,
  "skipped_reason": "string",
  "warnings": [
    "string"
  ],
  "workspace_id": "string",
  "write_target": "global-config"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

Read the current AGH 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
}
{
  "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"
  },
  "error": "string"
}
{
  "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"
  },
  "error": "string"
}
Empty

Logs

AGH Logs HTTP endpoints.

Support

AGH Support HTTP endpoints.