archastro.platform.v1.resources.config
1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. 2# This file is auto-generated by @archastro/sdk-generator. Do not edit. 3# Content hash: d9371c141e7e 4 5from __future__ import annotations 6 7import builtins 8from datetime import datetime 9from typing import Any, Required, TypedDict 10 11from pydantic import BaseModel, Field 12 13from ...runtime.http_client import HttpClient, SyncHttpClient 14from ...types.common import ValidationResult 15from ...types.config import Config, ConfigFacets, ConfigKindSchema 16 17 18class SystemCloneInput(TypedDict, total=False): 19 "Clone a system config" 20 21 lookup_key: str | None 22 "Override the `lookup_key` on the cloned config. When omitted, the source value is used." 23 org: str | None 24 "Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org." 25 team: str | None 26 "Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped." 27 user: str | None 28 "User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped." 29 virtual_path: str | None 30 "Override the `virtual_path` on the cloned config. When omitted, the source value is used." 31 32 33class ConfigCreateInput(TypedDict, total=False): 34 "Create a config" 35 36 agent: str | None 37 "Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`." 38 change_description: str | None 39 "Human-readable description of this initial version, stored on the version record." 40 data: dict[str, Any] | None 41 "Arbitrary key-value metadata stored on the version alongside the content." 42 data_encoding: str | None 43 'Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON.' 44 kind: Required[str] 45 'Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`.' 46 lookup_key: str | None 47 "Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners." 48 mime_type: Required[str] 49 'MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`.' 50 org: str | None 51 "Organization ID (`org_...`) to scope the config to a specific org." 52 parent: str | None 53 "Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config." 54 parent_solution: str | None 55 "Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle." 56 raw_content: Required[str] 57 "Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text." 58 relative_path: str | None 59 'Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set.' 60 system: bool | None 61 "Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`." 62 take_ownership: bool | None 63 "When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer)." 64 team: str | None 65 "Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`." 66 user: str | None 67 "User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`." 68 virtual_path: str | None 69 'Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination.' 70 71 72class ConfigEncryptSecretInput(TypedDict, total=False): 73 "Encrypt a secret for use in a config" 74 75 org: str | None 76 "Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context." 77 plaintext: Required[str] 78 "The secret value to encrypt. Never stored; only the resulting ciphertext is returned." 79 80 81class ConfigValidateInput(TypedDict, total=False): 82 "Validate config content" 83 84 agent: str | None 85 "Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`." 86 data: dict[str, Any] | None 87 "Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content." 88 data_encoding: str | None 89 'Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON.' 90 kind: Required[str] 91 'Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`.' 92 mime_type: Required[str] 93 'MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation.' 94 raw_content: Required[str] 95 "Raw content bytes to validate. Parsed according to `mime_type` before schema validation." 96 team: str | None 97 "Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`." 98 user: str | None 99 "User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`." 100 101 102class ConfigUpdateInput(TypedDict, total=False): 103 "Update a config" 104 105 agent: str | None 106 "Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 107 change_description: str | None 108 "Human-readable description of this update, stored on the new version record." 109 data: dict[str, Any] | None 110 "Arbitrary key-value metadata to store on the new version alongside the content." 111 data_encoding: str | None 112 'Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON.' 113 expected_version: int | None 114 "Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking." 115 lookup_key: str | None 116 "New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted." 117 mime_type: str | None 118 'MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field.' 119 org: str | None 120 "Organization ID (`org_...`) to narrow the lookup to configs belonging to that org." 121 parent_solution: str | None 122 "Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string." 123 raw_content: str | None 124 "New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version." 125 relative_path: str | None 126 "Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`." 127 system: bool | None 128 "Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin." 129 team: str | None 130 "Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 131 user: str | None 132 "User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 133 virtual_path: str | None 134 "New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted." 135 136 137class ConfigArchiveInput(TypedDict, total=False): 138 "Archive a config" 139 140 agent: str | None 141 "Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 142 org: str | None 143 "Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs." 144 system: bool | None 145 "Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin." 146 team: str | None 147 "Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 148 user: str | None 149 "User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 150 151 152class ConfigChangeOwnerInput(TypedDict, total=False): 153 "Transfer ownership of a config" 154 155 agent: str | None 156 "New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`." 157 org: str | None 158 "Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422." 159 system: bool | None 160 "Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`." 161 team: str | None 162 "New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`." 163 user: str | None 164 "New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`." 165 166 167class ConfigUnarchiveInput(TypedDict, total=False): 168 "Unarchive a config" 169 170 agent: str | None 171 "Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 172 org: str | None 173 "Organization ID (`org_...`) to narrow the lookup to configs belonging to that org." 174 system: bool | None 175 "Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin." 176 team: str | None 177 "Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 178 user: str | None 179 "User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 180 181 182class KindListResponseDataItem(BaseModel): 183 classification: str = Field( 184 ..., 185 description='Structural role of this kind. `"root"` kinds are standalone configs; `"supplemental"` kinds extend or augment a root config.', 186 ) 187 description: str | None = Field( 188 default=None, 189 description="Markdown prose describing what this config kind represents and how to use it. `null` when no description has been registered for this kind.", 190 ) 191 kind: str = Field( 192 ..., 193 description='The config kind identifier (e.g., `"Agent"`, `"APITool"`). Used as the `kind` value when creating or filtering configs.', 194 ) 195 sample_available: bool = Field( 196 ..., 197 description="`true` when a sample YAML document is available for this kind via the schema endpoint.", 198 ) 199 schema_available: bool = Field( 200 ..., 201 description="`true` when a JSON Schema definition is available for this kind via the schema endpoint.", 202 ) 203 204 205class KindListResponse(BaseModel): 206 """ 207 Successful response 208 """ 209 210 data: list[KindListResponseDataItem] = Field( 211 ..., description="Array of config kind objects, sorted alphabetically by `kind` name." 212 ) 213 214 215class SystemListResponseDataItemCurrentVersion(BaseModel): 216 change_description: str | None = Field( 217 default=None, 218 description="Human-readable summary of what changed in this version, as provided by the author. `null` if no description was supplied.", 219 ) 220 content_hash: str | None = Field( 221 default=None, 222 description="SHA-256 digest of the raw config content encoded as `sha256:<hex>`. Uses the same algorithm as the CLI `computeContentHash` helper. `null` for versions created before this field was introduced.", 223 ) 224 created_at: datetime | None = Field( 225 default=None, description="When this config version was created (ISO 8601)." 226 ) 227 data: dict[str, Any] | None = Field( 228 default=None, 229 description="Arbitrary structured metadata stored alongside this version. `null` when no extra data was provided.", 230 ) 231 id: str = Field(..., description="Config version ID (`cfv_...`).") 232 org: str | None = Field( 233 default=None, 234 description="Organization ID (`org_...`) that owns this config version. `null` for personal configs.", 235 ) 236 sandbox: str | None = Field( 237 default=None, 238 description="Sandbox ID (`sbx_...`) this version was saved under. `null` for production configs.", 239 ) 240 source_solution_config_version: str | None = Field( 241 default=None, 242 description="Config version ID (`cfv_...`) for the Solution version this config version was installed from. `null` for standalone configs and legacy rows.", 243 ) 244 version_number: int = Field( 245 ..., 246 description="Monotonically increasing integer identifying this version within the config. Starts at 1.", 247 ) 248 249 250class SystemListResponseDataItem(BaseModel): 251 agent: str | None = Field( 252 default=None, 253 description="Agent ID (`agt_...`) associated with this config. `null` if not linked to an agent.", 254 ) 255 created_at: datetime | None = Field( 256 default=None, description="When this config was first created (ISO 8601)." 257 ) 258 current_version: SystemListResponseDataItemCurrentVersion | None = Field( 259 default=None, 260 description="The most recently saved version of this config. `null` if the config has never been saved with content.", 261 ) 262 id: str = Field(..., description="Config ID (`cfg_...`).") 263 is_archived: bool | None = Field( 264 default=None, 265 description="Whether this config has been archived. Archived configs are hidden from default listings but remain accessible by ID.", 266 ) 267 kind: str = Field( 268 ..., 269 description='Type of config, e.g. `"Agent"` or `"APITool"`. Determines which fields and validation rules apply.', 270 ) 271 lookup_key: str | None = Field( 272 default=None, 273 description="Stable, user-defined key used to look up this config without knowing its ID. `null` if not set.", 274 ) 275 mime_type: str | None = Field( 276 default=None, 277 description='MIME type of the config\'s content, e.g. `"text/yaml"`. `null` if not determined.', 278 ) 279 org: str | None = Field( 280 default=None, 281 description="Organization ID (`org_...`) this config belongs to. `null` for configs not scoped to an org.", 282 ) 283 parent: str | None = Field( 284 default=None, 285 description="Parent bundle config ID (`cfg_...`). Present only for configs that are children of a bundle; `null` otherwise.", 286 ) 287 parent_solution: str | None = Field( 288 default=None, 289 description="ID (`cfg_...`) of the solution config this config was imported with. `null` if the config was not imported via a solution.", 290 ) 291 raw_content: str | None = Field( 292 default=None, 293 description="Raw file content as a string. Populated only for system configs; `null` for user-owned configs.", 294 ) 295 relative_path: str | None = Field( 296 default=None, 297 description="Path of this config relative to its parent bundle root. Present only for bundle children; `null` otherwise.", 298 ) 299 sandbox: str | None = Field( 300 default=None, 301 description="Sandbox identifier this config belongs to. `null` for production configs.", 302 ) 303 team: str | None = Field( 304 default=None, 305 description="Team ID (`tea_...`) that owns this config. `null` for personal (user-scoped) configs.", 306 ) 307 updated_at: datetime | None = Field( 308 default=None, description="When this config was last modified (ISO 8601)." 309 ) 310 user: str | None = Field( 311 default=None, 312 description="User ID (`usr_...`) who owns this config. `null` for team-scoped configs.", 313 ) 314 virtual_path: str | None = Field( 315 default=None, 316 description='Logical path uniquely identifying this config within its team, e.g. `"agents/my-agent.yaml"`. `null` for configs without an explicit path.', 317 ) 318 319 320class SystemListResponse(BaseModel): 321 """ 322 Successful response 323 """ 324 325 data: list[SystemListResponseDataItem] = Field( 326 ..., description="Array of system config objects for the current page." 327 ) 328 has_next: bool = Field(..., description="`true` when a subsequent page of results exists.") 329 has_prev: bool = Field(..., description="`true` when a previous page of results exists.") 330 page: int = Field(..., description="The current page number (1-indexed).") 331 page_size: int = Field(..., description="Number of results returned per page.") 332 total_entries: int = Field( 333 ..., 334 description="Total number of system configs matching the applied filters across all pages.", 335 ) 336 total_pages: int = Field( 337 ..., description="Total number of pages given the current `page_size`." 338 ) 339 340 341class ConfigListResponseDataItemCurrentVersion(BaseModel): 342 change_description: str | None = Field( 343 default=None, 344 description="Human-readable summary of what changed in this version, as provided by the author. `null` if no description was supplied.", 345 ) 346 content_hash: str | None = Field( 347 default=None, 348 description="SHA-256 digest of the raw config content encoded as `sha256:<hex>`. Uses the same algorithm as the CLI `computeContentHash` helper. `null` for versions created before this field was introduced.", 349 ) 350 created_at: datetime | None = Field( 351 default=None, description="When this config version was created (ISO 8601)." 352 ) 353 data: dict[str, Any] | None = Field( 354 default=None, 355 description="Arbitrary structured metadata stored alongside this version. `null` when no extra data was provided.", 356 ) 357 id: str = Field(..., description="Config version ID (`cfv_...`).") 358 org: str | None = Field( 359 default=None, 360 description="Organization ID (`org_...`) that owns this config version. `null` for personal configs.", 361 ) 362 sandbox: str | None = Field( 363 default=None, 364 description="Sandbox ID (`sbx_...`) this version was saved under. `null` for production configs.", 365 ) 366 source_solution_config_version: str | None = Field( 367 default=None, 368 description="Config version ID (`cfv_...`) for the Solution version this config version was installed from. `null` for standalone configs and legacy rows.", 369 ) 370 version_number: int = Field( 371 ..., 372 description="Monotonically increasing integer identifying this version within the config. Starts at 1.", 373 ) 374 375 376class ConfigListResponseDataItem(BaseModel): 377 agent: str | None = Field( 378 default=None, 379 description="Agent ID (`agt_...`) associated with this config. `null` if not linked to an agent.", 380 ) 381 created_at: datetime | None = Field( 382 default=None, description="When this config was first created (ISO 8601)." 383 ) 384 current_version: ConfigListResponseDataItemCurrentVersion | None = Field( 385 default=None, 386 description="The most recently saved version of this config. `null` if the config has never been saved with content.", 387 ) 388 id: str = Field(..., description="Config ID (`cfg_...`).") 389 is_archived: bool | None = Field( 390 default=None, 391 description="Whether this config has been archived. Archived configs are hidden from default listings but remain accessible by ID.", 392 ) 393 kind: str = Field( 394 ..., 395 description='Type of config, e.g. `"Agent"` or `"APITool"`. Determines which fields and validation rules apply.', 396 ) 397 lookup_key: str | None = Field( 398 default=None, 399 description="Stable, user-defined key used to look up this config without knowing its ID. `null` if not set.", 400 ) 401 mime_type: str | None = Field( 402 default=None, 403 description='MIME type of the config\'s content, e.g. `"text/yaml"`. `null` if not determined.', 404 ) 405 org: str | None = Field( 406 default=None, 407 description="Organization ID (`org_...`) this config belongs to. `null` for configs not scoped to an org.", 408 ) 409 parent: str | None = Field( 410 default=None, 411 description="Parent bundle config ID (`cfg_...`). Present only for configs that are children of a bundle; `null` otherwise.", 412 ) 413 parent_solution: str | None = Field( 414 default=None, 415 description="ID (`cfg_...`) of the solution config this config was imported with. `null` if the config was not imported via a solution.", 416 ) 417 raw_content: str | None = Field( 418 default=None, 419 description="Raw file content as a string. Populated only for system configs; `null` for user-owned configs.", 420 ) 421 relative_path: str | None = Field( 422 default=None, 423 description="Path of this config relative to its parent bundle root. Present only for bundle children; `null` otherwise.", 424 ) 425 sandbox: str | None = Field( 426 default=None, 427 description="Sandbox identifier this config belongs to. `null` for production configs.", 428 ) 429 team: str | None = Field( 430 default=None, 431 description="Team ID (`tea_...`) that owns this config. `null` for personal (user-scoped) configs.", 432 ) 433 updated_at: datetime | None = Field( 434 default=None, description="When this config was last modified (ISO 8601)." 435 ) 436 user: str | None = Field( 437 default=None, 438 description="User ID (`usr_...`) who owns this config. `null` for team-scoped configs.", 439 ) 440 virtual_path: str | None = Field( 441 default=None, 442 description='Logical path uniquely identifying this config within its team, e.g. `"agents/my-agent.yaml"`. `null` for configs without an explicit path.', 443 ) 444 445 446class ConfigListResponse(BaseModel): 447 """ 448 Successful response 449 """ 450 451 data: list[ConfigListResponseDataItem] = Field( 452 ..., description="Array of config objects matching the query." 453 ) 454 455 456class ConfigEncryptSecretResponse(BaseModel): 457 """ 458 Successful response 459 """ 460 461 encrypted_value: str = Field( 462 ..., 463 description="Encrypted ciphertext string. Embed this in config content using the `secret_value!` interpolation syntax to have it decrypted at runtime.", 464 ) 465 466 467class ConfigVersionsResponseVersionsItem(BaseModel): 468 change_description: str | None = Field( 469 default=None, 470 description="Human-readable summary of what changed in this version, as provided by the author. `null` if no description was supplied.", 471 ) 472 content_hash: str | None = Field( 473 default=None, 474 description="SHA-256 digest of the raw config content encoded as `sha256:<hex>`. Uses the same algorithm as the CLI `computeContentHash` helper. `null` for versions created before this field was introduced.", 475 ) 476 created_at: datetime | None = Field( 477 default=None, description="When this config version was created (ISO 8601)." 478 ) 479 data: dict[str, Any] | None = Field( 480 default=None, 481 description="Arbitrary structured metadata stored alongside this version. `null` when no extra data was provided.", 482 ) 483 id: str = Field(..., description="Config version ID (`cfv_...`).") 484 org: str | None = Field( 485 default=None, 486 description="Organization ID (`org_...`) that owns this config version. `null` for personal configs.", 487 ) 488 sandbox: str | None = Field( 489 default=None, 490 description="Sandbox ID (`sbx_...`) this version was saved under. `null` for production configs.", 491 ) 492 source_solution_config_version: str | None = Field( 493 default=None, 494 description="Config version ID (`cfv_...`) for the Solution version this config version was installed from. `null` for standalone configs and legacy rows.", 495 ) 496 version_number: int = Field( 497 ..., 498 description="Monotonically increasing integer identifying this version within the config. Starts at 1.", 499 ) 500 501 502class ConfigVersionsResponse(BaseModel): 503 """ 504 Successful response 505 """ 506 507 versions: list[ConfigVersionsResponseVersionsItem] = Field( 508 ..., description="Array of version objects ordered from most recent to oldest." 509 ) 510 511 512class AsyncKindResource: 513 def __init__(self, http: HttpClient): 514 self._http = http 515 516 async def list(self, *, kind: builtins.list[str] | None = None) -> KindListResponse: 517 """ 518 List config kinds 519 Returns all config kinds registered in the platform, sorted alphabetically by name. 520 Each entry describes a type of configuration object (e.g., `"Agent"`, `"APITool"`) and 521 indicates whether a JSON schema and a YAML sample are available for it. 522 Any authenticated user may call this endpoint; no ownership scope is required. 523 Pass one or more `kind` values to restrict the response to those specific kinds. 524 Omit the parameter to receive the full list of non-private kinds. 525 526 Args: 527 kind: One or more config kind names to include in the response (e.g., `"Agent"`, `"APITool"`). Omit to return all non-private kinds. 528 529 Returns: 530 Successful response 531 """ 532 query: dict[str, object] = {} 533 if kind is not None: 534 query["kind"] = kind 535 return await self._http.request( 536 "/api/v1/config/kinds", 537 query=query, 538 response_type=KindListResponse, 539 ) 540 541 async def schema(self, kind: str) -> ConfigKindSchema: 542 """ 543 Retrieve a config kind schema 544 Returns the JSON schema and a YAML sample for a single config kind. Use this to 545 understand the structure a config object of that kind must follow before creating 546 or validating one. 547 The `json_schema` field is `null` when the kind has no machine-readable schema 548 defined. The `sample_yaml` field is `null` when no sample is available. Any 549 authenticated user may call this endpoint; no ownership scope is required. 550 Returns 404 if the kind name does not match a registered, non-private config kind. 551 552 Args: 553 kind: Name of the config kind to retrieve (e.g., `"Agent"`, `"APITool"`). Must match a registered, non-private kind exactly. 554 555 Returns: 556 The JSON schema and YAML sample for the requested config kind. 557 """ 558 return await self._http.request( 559 f"/api/v1/config/kinds/{kind}/schema", 560 response_type=ConfigKindSchema, 561 ) 562 563 564class AsyncSystemResource: 565 def __init__(self, http: HttpClient): 566 self._http = http 567 568 async def list( 569 self, 570 *, 571 kind: str | None = None, 572 kinds: builtins.list[str] | None = None, 573 excluded_path_prefixes: builtins.list[str] | None = None, 574 page: int | None = None, 575 page_size: int | None = None, 576 ) -> SystemListResponse: 577 """ 578 List system configs 579 Returns a paginated list of system (template) configs from the filesystem-backed 580 manifest. Results are always ordered by `virtual_path` ascending. 581 Filter by one or more config kinds using `kind` (single value) or `kinds` (array). 582 Both filters may be supplied together for backward compatibility; `kinds` takes 583 precedence when both are present. Exclude specific path namespaces with 584 `excluded_path_prefixes`. 585 Use `page` and `page_size` to paginate. Page size is clamped to a maximum of 200; 586 requests exceeding this limit are silently clamped rather than rejected. 587 588 Args: 589 kind: Filter results to a single config kind, e.g. `"Agent"` or `"APITool"`. Use `kinds` to filter by multiple kinds at once. 590 kinds: Filter results to configs whose `kind` is in this list. When both `kind` and `kinds` are provided, `kinds` takes precedence. 591 excluded_path_prefixes: Exclude configs whose `virtual_path` starts with any of the listed string prefixes. 592 page: Page number to retrieve, 1-indexed. Defaults to `1`. 593 page_size: Number of results per page. Defaults to `50`; maximum is `200`. Values above the maximum are clamped to `200`. 594 595 Returns: 596 Successful response 597 """ 598 query: dict[str, object] = {} 599 if kind is not None: 600 query["kind"] = kind 601 if kinds is not None: 602 query["kinds"] = kinds 603 if excluded_path_prefixes is not None: 604 query["excluded_path_prefixes"] = excluded_path_prefixes 605 if page is not None: 606 query["page"] = page 607 if page_size is not None: 608 query["page_size"] = page_size 609 return await self._http.request( 610 "/api/v1/config/system", 611 query=query, 612 response_type=SystemListResponse, 613 ) 614 615 async def facets(self) -> ConfigFacets: 616 """ 617 Retrieve system config facets 618 Returns the distinct `kind` values and leading `virtual_path` prefixes present 619 in the system (template) config manifest, each accompanied by a count of matching 620 configs. Use this data to populate filter UIs or to determine which config kinds 621 are available before listing or cloning. 622 The response reflects the filesystem-backed template manifest and does not include 623 user- or team-owned configs. 624 625 Returns: 626 Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs. 627 """ 628 return await self._http.request("/api/v1/config/system/facets", response_type=ConfigFacets) 629 630 async def get(self, system: str) -> Config: 631 """ 632 Retrieve a system config 633 Returns a single system (template) config identified by its `virtual_path` or 634 `lookup_key`. The `system` parameter value is URL-decoded before lookup, so 635 path segments with special characters may be passed URL-encoded. 636 System configs are filesystem-backed templates and are readable by any 637 authenticated caller regardless of team or user ownership. Returns 404 when no 638 system config matches the given identifier. 639 640 Args: 641 system: Identifier of the system config to retrieve either its `virtual_path` or its `lookup_key`. May be URL-encoded. 642 643 Returns: 644 The requested system config, including its current version and all metadata fields. 645 """ 646 return await self._http.request(f"/api/v1/config/system/{system}", response_type=Config) 647 648 async def clone(self, system: str, input: SystemCloneInput) -> Config: 649 """ 650 Clone a system config 651 Creates a copy of a system (template) config and transfers ownership to a team 652 or user. All dependencies bundled with the source config are cloned alongside it. 653 Responds with HTTP 201 and the newly created config on success. 654 You must specify exactly one destination owner via `team` or `user`. Callers 655 authenticated as an app (developer portal) may omit the owner the clone is 656 then scoped to the system owner automatically. 657 Use `virtual_path` and `lookup_key` to override the corresponding fields on the 658 clone; omitting them carries the values from the source. 659 660 Args: 661 system: Identifier of the source system config either its `virtual_path` or its `lookup_key`. 662 input: Request body. 663 input.lookup_key: Override the `lookup_key` on the cloned config. When omitted, the source value is used. 664 input.org: Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org. 665 input.team: Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped. 666 input.user: User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped. 667 input.virtual_path: Override the `virtual_path` on the cloned config. When omitted, the source value is used. 668 669 Returns: 670 The newly created config, including all cloned fields and its assigned ID. 671 """ 672 return await self._http.request( 673 f"/api/v1/config/system/{system}/clone", 674 method="POST", 675 body=input, 676 response_type=Config, 677 ) 678 679 680class AsyncConfigResource: 681 def __init__(self, http: HttpClient): 682 self._http = http 683 self.kinds = AsyncKindResource(http) 684 self.system = AsyncSystemResource(http) 685 686 async def list( 687 self, 688 *, 689 team: str | None = None, 690 user: str | None = None, 691 agent: str | None = None, 692 kind: str | None = None, 693 lookup_key: str | None = None, 694 path_prefix: str | None = None, 695 parents: builtins.list[str] | None = None, 696 parent_solutions: builtins.list[str] | None = None, 697 ) -> ConfigListResponse: 698 """ 699 List configs 700 Returns all configs owned by the specified owner. Exactly one owner selector 701 (`team`, `user`, or `agent`) must be provided. Passing an unknown or 702 inaccessible owner returns an empty `data` array rather than an error, to 703 avoid leaking information about which teams, users, or agents exist. 704 Use the `kind`, `lookup_key`, `path_prefix`, `parents`, and 705 `parent_solutions` params to narrow results. Private config kinds are always 706 excluded from the response regardless of the viewer's permissions. 707 Results are not paginated; all matching configs are returned in a single 708 response. 709 710 Args: 711 team: Team ID (`team_...`) whose configs to list. Mutually exclusive with `user` and `agent`. 712 user: User ID (`usr_...`) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive with `team` and `agent`. 713 agent: Agent ID (`agt_...`) whose configs to list. Mutually exclusive with `team` and `user`. 714 kind: Filter results to configs of this kind, e.g. `"Agent"` or `"APITool"`. Omit to return configs of all non-private kinds. 715 lookup_key: Filter to the config with exactly this `lookup_key`. Returns at most one result. 716 path_prefix: Filter to configs whose `virtual_path` starts with this prefix, e.g. `"my-agent/"`. Useful for listing files within a folder. 717 parents: Filter to configs that are children of any of the listed parent config IDs (`cfg_...`). Pass a single ID to retrieve all children of one bundle. 718 parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (`cfg_...`). Useful for identifying all files that arrived with a given solution. 719 720 Returns: 721 Successful response 722 """ 723 query: dict[str, object] = {} 724 if team is not None: 725 query["team"] = team 726 if user is not None: 727 query["user"] = user 728 if agent is not None: 729 query["agent"] = agent 730 if kind is not None: 731 query["kind"] = kind 732 if lookup_key is not None: 733 query["lookup_key"] = lookup_key 734 if path_prefix is not None: 735 query["path_prefix"] = path_prefix 736 if parents is not None: 737 query["parents"] = parents 738 if parent_solutions is not None: 739 query["parent_solutions"] = parent_solutions 740 return await self._http.request( 741 "/api/v1/config", 742 query=query, 743 response_type=ConfigListResponse, 744 ) 745 746 async def create(self, input: ConfigCreateInput) -> Config: 747 """ 748 Create a config 749 Creates a new config and its first version. Returns 201 on success. 750 A config is uniquely identified within an app + org scope by its 751 `virtual_path` or `lookup_key`. Creating a config at a path that already 752 exists (including archived configs) returns 409. To adopt an existing config 753 at that path and re-own it instead, pass `take_ownership: true` this 754 requires modify rights on the existing row (developer or all-powerful viewer). 755 The owner is resolved from the explicit selector params (`team`, `user`, 756 `agent`, or `system`). Developer and all-powerful viewers default to system 757 ownership when no explicit selector is provided. Exactly one owner selector 758 may be set; conflicting selectors return 422. 759 Requires app scope. 760 761 Args: 762 input: Request body. 763 input.agent: Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`. 764 input.change_description: Human-readable description of this initial version, stored on the version record. 765 input.data: Arbitrary key-value metadata stored on the version alongside the content. 766 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 767 input.kind: Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`. 768 input.lookup_key: Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners. 769 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. 770 input.org: Organization ID (`org_...`) to scope the config to a specific org. 771 input.parent: Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config. 772 input.parent_solution: Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. 773 input.raw_content: Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text. 774 input.relative_path: Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set. 775 input.system: Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`. 776 input.take_ownership: When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). 777 input.team: Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`. 778 input.user: User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`. 779 input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination. 780 781 Returns: 782 The newly created config, including its first version. 783 """ 784 return await self._http.request( 785 "/api/v1/config", 786 method="POST", 787 body=input, 788 response_type=Config, 789 ) 790 791 async def encrypt_secret(self, input: ConfigEncryptSecretInput) -> ConfigEncryptSecretResponse: 792 """ 793 Encrypt a secret for use in a config 794 Encrypts a plaintext secret and returns a ciphertext string safe for 795 embedding directly in config content using the `secret_value!` interpolation 796 syntax. The ciphertext is bound to the app's (or org's) key-encryption key 797 (KEK) so it can only be decrypted at runtime within the same scope. 798 When `org` is provided, the KEK for that org is used; otherwise the 799 viewer's own org KEK is used, falling back to the app-level KEK for viewers 800 with no org context. 801 The plaintext is never stored. Requires app scope. 802 803 Args: 804 input: Request body. 805 input.org: Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. 806 input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned. 807 808 Returns: 809 Successful response 810 """ 811 return await self._http.request( 812 "/api/v1/config/encrypt_secret", 813 method="POST", 814 body=input, 815 response_type=ConfigEncryptSecretResponse, 816 ) 817 818 async def facets( 819 self, 820 *, 821 app: str | None = None, 822 team: str | None = None, 823 user: str | None = None, 824 org: str | None = None, 825 ) -> ConfigFacets: 826 """ 827 List config facets 828 Returns the distinct config kinds and leading `virtual_path` prefixes 829 available to the viewer, each with a count of matching configs. Use this 830 to populate filter UI dropdowns without making a full list request. 831 The counts reflect every config the viewer can see in the requested scope, 832 independent of any kind, path-prefix, or lookup-key filters that might be 833 applied on a concurrent list request. This means the UI always shows every 834 option the viewer could pick, not just the values on the current filtered page. 835 Scoping follows the same rules as the list endpoint: developer and 836 all-powerful viewers see facets across all owners in the app; org-scoped 837 viewers receive their own configs' facets merged with system-owned facets; 838 all other viewers see only their resolved owner's configs. 839 840 Args: 841 app: App ID (`app_...`). Present when mounted under the developer scope; injected automatically. 842 team: Team ID (`team_...`) to scope facets to that team's configs. Mutually exclusive with `user`. 843 user: User ID (`usr_...`) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive with `team`. 844 org: Organization ID (`org_...`) to narrow facets to configs belonging to that org. 845 846 Returns: 847 Distinct config kinds and `virtual_path` prefixes with per-value counts. 848 """ 849 query: dict[str, object] = {} 850 if app is not None: 851 query["app"] = app 852 if team is not None: 853 query["team"] = team 854 if user is not None: 855 query["user"] = user 856 if org is not None: 857 query["org"] = org 858 return await self._http.request( 859 "/api/v1/config/facets", 860 query=query, 861 response_type=ConfigFacets, 862 ) 863 864 async def validate(self, input: ConfigValidateInput) -> ValidationResult: 865 """ 866 Validate config content 867 Validates raw config content against the schema for a given config kind 868 without saving anything. Returns a structured result indicating whether the 869 content is valid and, if not, a list of error messages. 870 Use this endpoint to give users early feedback before calling create or 871 update. The owner context is used for any kind-specific validation rules that 872 are owner-aware; provide the same owner you intend to use on the write call. 873 Requires app scope. 874 875 Args: 876 input: Request body. 877 input.agent: Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`. 878 input.data: Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content. 879 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 880 input.kind: Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`. 881 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation. 882 input.raw_content: Raw content bytes to validate. Parsed according to `mime_type` before schema validation. 883 input.team: Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`. 884 input.user: User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`. 885 886 Returns: 887 Validation outcome. Always HTTP 200; check the `valid` field to determine success. Includes `errors` when `valid` is `false`. 888 """ 889 return await self._http.request( 890 "/api/v1/config/validate", 891 method="POST", 892 body=input, 893 response_type=ValidationResult, 894 ) 895 896 async def delete(self, config: str) -> None: 897 """ 898 Delete a config 899 Permanently deletes a config and all its associated versions. This action is 900 irreversible. To soft-delete a config while retaining its history, use the 901 archive endpoint instead. 902 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 903 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 904 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 905 passing an owner selector when addressing by ID returns 422. 906 Returns 204 No Content on success. Requires app scope. The viewer must have 907 modify rights on the config. 908 909 Args: 910 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 911 912 Returns: 913 Empty body. HTTP 204 indicates the config and all its versions were permanently deleted. 914 """ 915 await self._http.request(f"/api/v1/config/{config}", method="DELETE") 916 917 async def get( 918 self, 919 config: str, 920 *, 921 team: str | None = None, 922 user: str | None = None, 923 agent: str | None = None, 924 system: bool | None = None, 925 org: str | None = None, 926 ) -> Config: 927 """ 928 Retrieve a config 929 Returns a single config identified by its ID, `virtual_path`, or 930 `lookup_key`. The config object includes its current version metadata but 931 not the raw content bytes; use the content endpoint to fetch the raw content. 932 When addressing by `lookup_key` or `virtual_path`, you must supply exactly 933 one owner selector (`team`, `user`, `agent`, or `system`). Passing an owner 934 selector when addressing by ID (`cfg_...`) returns 422. Both `not_found` 935 and `forbidden` outcomes are surfaced as 404 to avoid leaking config 936 existence. 937 Requires app scope. 938 939 Args: 940 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 941 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 942 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 943 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 944 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 945 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 946 947 Returns: 948 The requested config object. 949 """ 950 query: dict[str, object] = {} 951 if team is not None: 952 query["team"] = team 953 if user is not None: 954 query["user"] = user 955 if agent is not None: 956 query["agent"] = agent 957 if system is not None: 958 query["system"] = system 959 if org is not None: 960 query["org"] = org 961 return await self._http.request( 962 f"/api/v1/config/{config}", 963 query=query, 964 response_type=Config, 965 ) 966 967 async def update(self, config: str, input: ConfigUpdateInput) -> Config: 968 """ 969 Update a config 970 Updates an existing config. When `raw_content` is provided, a new version is 971 created and becomes the current version. When `raw_content` is omitted, only 972 metadata fields (`virtual_path`, `lookup_key`, `relative_path`, 973 `parent_solution`) are updated without creating a new version. 974 Use `expected_version` for optimistic concurrency control: if the config's 975 current version number does not match the supplied value the request returns 976 409. This prevents overwriting concurrent edits. 977 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 978 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 979 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 980 Both `not_found` and `forbidden` outcomes are surfaced as 404. 981 Requires app scope. The viewer must have modify rights on the config. 982 983 Args: 984 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 985 input: Request body. 986 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 987 input.change_description: Human-readable description of this update, stored on the new version record. 988 input.data: Arbitrary key-value metadata to store on the new version alongside the content. 989 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 990 input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking. 991 input.lookup_key: New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted. 992 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field. 993 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 994 input.parent_solution: Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string. 995 input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version. 996 input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`. 997 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 998 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 999 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1000 input.virtual_path: New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted. 1001 1002 Returns: 1003 The config reflecting the applied update. 1004 """ 1005 return await self._http.request( 1006 f"/api/v1/config/{config}", 1007 method="PATCH", 1008 body=input, 1009 response_type=Config, 1010 ) 1011 1012 async def archive(self, config: str, input: ConfigArchiveInput) -> Config: 1013 """ 1014 Archive a config 1015 Soft-deletes a config by marking it as archived. Archived configs are hidden 1016 from list and show endpoints but are not permanently removed; use the 1017 unarchive endpoint to restore one, or the delete endpoint for permanent 1018 removal. 1019 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1020 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1021 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1022 passing an owner selector when addressing by ID returns 422. 1023 Requires app scope. The viewer must have modify rights on the config. 1024 1025 Args: 1026 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. `virtual_path` values should be URL-encoded if they contain slashes. 1027 input: Request body. 1028 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1029 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. 1030 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1031 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1032 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1033 1034 Returns: 1035 The config in its newly archived state. 1036 """ 1037 return await self._http.request( 1038 f"/api/v1/config/{config}/archive", 1039 method="POST", 1040 body=input, 1041 response_type=Config, 1042 ) 1043 1044 async def change_owner(self, config: str, input: ConfigChangeOwnerInput) -> Config: 1045 """ 1046 Transfer ownership of a config 1047 Transfers a config to a new owner (`team`, `user`, `agent`, or `system`). 1048 Exactly one of the new-owner selectors must be provided. The config must be 1049 addressed by its ID (`cfg_...` or UUID); `virtual_path` and `lookup_key` 1050 are not accepted to avoid ambiguity look up the ID first if needed. 1051 For non-system targets the new owner's org is derived automatically from the 1052 target entity; supplying `org` in that case returns 422. For `system:true` 1053 targets, `org` controls the resulting org scope: omit to keep the existing 1054 `org_id`, supply a value to set a specific org, or pass `null`/blank to make 1055 the config app-level (operator viewers only). 1056 Operator viewers (developer credentials or all-powerful viewers) may transfer 1057 to any owner. All other viewers are restricted to owners they can themselves 1058 access (team membership, user identity, agent scope, or `system` with the 1059 appropriate privilege). 1060 Requires app scope. The viewer must have modify rights on the config. 1061 1062 Args: 1063 config: Config ID in id-form: `cfg_...` or a UUID. `lookup_key` and `virtual_path` are not accepted retrieve the config ID first if you only have a path. 1064 input: Request body. 1065 input.agent: New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`. 1066 input.org: Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422. 1067 input.system: Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`. 1068 input.team: New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`. 1069 input.user: New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`. 1070 1071 Returns: 1072 The config reflecting its new ownership. 1073 """ 1074 return await self._http.request( 1075 f"/api/v1/config/{config}/change_owner", 1076 method="POST", 1077 body=input, 1078 response_type=Config, 1079 ) 1080 1081 async def content( 1082 self, 1083 config: str, 1084 *, 1085 team: str | None = None, 1086 user: str | None = None, 1087 agent: str | None = None, 1088 system: bool | None = None, 1089 org: str | None = None, 1090 format: str | None = None, 1091 inject_protected_fields: bool | None = None, 1092 ) -> dict[str, str]: 1093 """ 1094 Retrieve a config's raw content 1095 Returns the raw byte content of a config's current version. The response 1096 `Content-Type` header reflects the config's stored MIME type unless a 1097 `format` conversion is requested. 1098 Pass `format: "yaml"` or `format: "json"` to convert between YAML and JSON 1099 on the fly. Conversion is only supported between these two formats; requesting 1100 a conversion that is not possible returns 400. 1101 By default, `virtual_path` and other platform-injected protected fields are 1102 embedded in the returned content. Set `inject_protected_fields: false` to 1103 return the stored raw bytes exactly as written. 1104 The config may be addressed by ID (`cfg_...`), `virtual_path`, or 1105 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, exactly one 1106 owner selector (`team`, `user`, `agent`, or `system`) is required. 1107 1108 Args: 1109 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1110 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1111 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1112 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1113 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1114 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1115 format: Output format for content conversion. One of `"yaml"` or `"json"`. Omit to return the content in its stored format. Returns 400 if conversion is not possible. 1116 inject_protected_fields: Whether to inject platform-managed protected fields (such as `virtual_path`) into the returned content. Defaults to `true`. Set to `false` to receive the raw stored bytes. 1117 1118 Returns: 1119 Raw config content in the stored or requested format. 1120 """ 1121 query: dict[str, object] = {} 1122 if team is not None: 1123 query["team"] = team 1124 if user is not None: 1125 query["user"] = user 1126 if agent is not None: 1127 query["agent"] = agent 1128 if system is not None: 1129 query["system"] = system 1130 if org is not None: 1131 query["org"] = org 1132 if format is not None: 1133 query["format"] = format 1134 if inject_protected_fields is not None: 1135 query["inject_protected_fields"] = inject_protected_fields 1136 return await self._http.request_raw(f"/api/v1/config/{config}/content", query=query) 1137 1138 async def unarchive(self, config: str, input: ConfigUnarchiveInput) -> Config: 1139 """ 1140 Unarchive a config 1141 Restores a previously archived config, making it visible again in list and 1142 show responses. The config's content and version history are unchanged. 1143 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1144 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1145 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1146 passing an owner selector when addressing by ID returns 422. 1147 Requires app scope. The viewer must have modify rights on the config. 1148 1149 Args: 1150 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1151 input: Request body. 1152 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1153 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1154 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1155 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1156 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1157 1158 Returns: 1159 The config in its newly restored (active) state. 1160 """ 1161 return await self._http.request( 1162 f"/api/v1/config/{config}/unarchive", 1163 method="POST", 1164 body=input, 1165 response_type=Config, 1166 ) 1167 1168 async def versions( 1169 self, 1170 config: str, 1171 *, 1172 team: str | None = None, 1173 user: str | None = None, 1174 agent: str | None = None, 1175 system: bool | None = None, 1176 org: str | None = None, 1177 ) -> ConfigVersionsResponse: 1178 """ 1179 List a config's version history 1180 Returns all versions of a config in the order they were created, most recent 1181 first. Each version includes its version number, content metadata, and change 1182 description. The raw content bytes for a specific version are not included; 1183 use the content endpoint to fetch them. 1184 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1185 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1186 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1187 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1188 Requires app scope. 1189 1190 Args: 1191 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1192 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1193 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1194 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1195 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1196 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1197 1198 Returns: 1199 Successful response 1200 """ 1201 query: dict[str, object] = {} 1202 if team is not None: 1203 query["team"] = team 1204 if user is not None: 1205 query["user"] = user 1206 if agent is not None: 1207 query["agent"] = agent 1208 if system is not None: 1209 query["system"] = system 1210 if org is not None: 1211 query["org"] = org 1212 return await self._http.request( 1213 f"/api/v1/config/{config}/versions", 1214 query=query, 1215 response_type=ConfigVersionsResponse, 1216 ) 1217 1218 1219class KindResource: 1220 def __init__(self, http: SyncHttpClient): 1221 self._http = http 1222 1223 def list(self, *, kind: builtins.list[str] | None = None) -> KindListResponse: 1224 """ 1225 List config kinds 1226 Returns all config kinds registered in the platform, sorted alphabetically by name. 1227 Each entry describes a type of configuration object (e.g., `"Agent"`, `"APITool"`) and 1228 indicates whether a JSON schema and a YAML sample are available for it. 1229 Any authenticated user may call this endpoint; no ownership scope is required. 1230 Pass one or more `kind` values to restrict the response to those specific kinds. 1231 Omit the parameter to receive the full list of non-private kinds. 1232 1233 Args: 1234 kind: One or more config kind names to include in the response (e.g., `"Agent"`, `"APITool"`). Omit to return all non-private kinds. 1235 1236 Returns: 1237 Successful response 1238 """ 1239 query: dict[str, object] = {} 1240 if kind is not None: 1241 query["kind"] = kind 1242 return self._http.request( 1243 "/api/v1/config/kinds", 1244 query=query, 1245 response_type=KindListResponse, 1246 ) 1247 1248 def schema(self, kind: str) -> ConfigKindSchema: 1249 """ 1250 Retrieve a config kind schema 1251 Returns the JSON schema and a YAML sample for a single config kind. Use this to 1252 understand the structure a config object of that kind must follow before creating 1253 or validating one. 1254 The `json_schema` field is `null` when the kind has no machine-readable schema 1255 defined. The `sample_yaml` field is `null` when no sample is available. Any 1256 authenticated user may call this endpoint; no ownership scope is required. 1257 Returns 404 if the kind name does not match a registered, non-private config kind. 1258 1259 Args: 1260 kind: Name of the config kind to retrieve (e.g., `"Agent"`, `"APITool"`). Must match a registered, non-private kind exactly. 1261 1262 Returns: 1263 The JSON schema and YAML sample for the requested config kind. 1264 """ 1265 return self._http.request( 1266 f"/api/v1/config/kinds/{kind}/schema", 1267 response_type=ConfigKindSchema, 1268 ) 1269 1270 1271class SystemResource: 1272 def __init__(self, http: SyncHttpClient): 1273 self._http = http 1274 1275 def list( 1276 self, 1277 *, 1278 kind: str | None = None, 1279 kinds: builtins.list[str] | None = None, 1280 excluded_path_prefixes: builtins.list[str] | None = None, 1281 page: int | None = None, 1282 page_size: int | None = None, 1283 ) -> SystemListResponse: 1284 """ 1285 List system configs 1286 Returns a paginated list of system (template) configs from the filesystem-backed 1287 manifest. Results are always ordered by `virtual_path` ascending. 1288 Filter by one or more config kinds using `kind` (single value) or `kinds` (array). 1289 Both filters may be supplied together for backward compatibility; `kinds` takes 1290 precedence when both are present. Exclude specific path namespaces with 1291 `excluded_path_prefixes`. 1292 Use `page` and `page_size` to paginate. Page size is clamped to a maximum of 200; 1293 requests exceeding this limit are silently clamped rather than rejected. 1294 1295 Args: 1296 kind: Filter results to a single config kind, e.g. `"Agent"` or `"APITool"`. Use `kinds` to filter by multiple kinds at once. 1297 kinds: Filter results to configs whose `kind` is in this list. When both `kind` and `kinds` are provided, `kinds` takes precedence. 1298 excluded_path_prefixes: Exclude configs whose `virtual_path` starts with any of the listed string prefixes. 1299 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1300 page_size: Number of results per page. Defaults to `50`; maximum is `200`. Values above the maximum are clamped to `200`. 1301 1302 Returns: 1303 Successful response 1304 """ 1305 query: dict[str, object] = {} 1306 if kind is not None: 1307 query["kind"] = kind 1308 if kinds is not None: 1309 query["kinds"] = kinds 1310 if excluded_path_prefixes is not None: 1311 query["excluded_path_prefixes"] = excluded_path_prefixes 1312 if page is not None: 1313 query["page"] = page 1314 if page_size is not None: 1315 query["page_size"] = page_size 1316 return self._http.request( 1317 "/api/v1/config/system", 1318 query=query, 1319 response_type=SystemListResponse, 1320 ) 1321 1322 def facets(self) -> ConfigFacets: 1323 """ 1324 Retrieve system config facets 1325 Returns the distinct `kind` values and leading `virtual_path` prefixes present 1326 in the system (template) config manifest, each accompanied by a count of matching 1327 configs. Use this data to populate filter UIs or to determine which config kinds 1328 are available before listing or cloning. 1329 The response reflects the filesystem-backed template manifest and does not include 1330 user- or team-owned configs. 1331 1332 Returns: 1333 Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs. 1334 """ 1335 return self._http.request("/api/v1/config/system/facets", response_type=ConfigFacets) 1336 1337 def get(self, system: str) -> Config: 1338 """ 1339 Retrieve a system config 1340 Returns a single system (template) config identified by its `virtual_path` or 1341 `lookup_key`. The `system` parameter value is URL-decoded before lookup, so 1342 path segments with special characters may be passed URL-encoded. 1343 System configs are filesystem-backed templates and are readable by any 1344 authenticated caller regardless of team or user ownership. Returns 404 when no 1345 system config matches the given identifier. 1346 1347 Args: 1348 system: Identifier of the system config to retrieve either its `virtual_path` or its `lookup_key`. May be URL-encoded. 1349 1350 Returns: 1351 The requested system config, including its current version and all metadata fields. 1352 """ 1353 return self._http.request(f"/api/v1/config/system/{system}", response_type=Config) 1354 1355 def clone(self, system: str, input: SystemCloneInput) -> Config: 1356 """ 1357 Clone a system config 1358 Creates a copy of a system (template) config and transfers ownership to a team 1359 or user. All dependencies bundled with the source config are cloned alongside it. 1360 Responds with HTTP 201 and the newly created config on success. 1361 You must specify exactly one destination owner via `team` or `user`. Callers 1362 authenticated as an app (developer portal) may omit the owner the clone is 1363 then scoped to the system owner automatically. 1364 Use `virtual_path` and `lookup_key` to override the corresponding fields on the 1365 clone; omitting them carries the values from the source. 1366 1367 Args: 1368 system: Identifier of the source system config either its `virtual_path` or its `lookup_key`. 1369 input: Request body. 1370 input.lookup_key: Override the `lookup_key` on the cloned config. When omitted, the source value is used. 1371 input.org: Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org. 1372 input.team: Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped. 1373 input.user: User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped. 1374 input.virtual_path: Override the `virtual_path` on the cloned config. When omitted, the source value is used. 1375 1376 Returns: 1377 The newly created config, including all cloned fields and its assigned ID. 1378 """ 1379 return self._http.request( 1380 f"/api/v1/config/system/{system}/clone", 1381 method="POST", 1382 body=input, 1383 response_type=Config, 1384 ) 1385 1386 1387class ConfigResource: 1388 def __init__(self, http: SyncHttpClient): 1389 self._http = http 1390 self.kinds = KindResource(http) 1391 self.system = SystemResource(http) 1392 1393 def list( 1394 self, 1395 *, 1396 team: str | None = None, 1397 user: str | None = None, 1398 agent: str | None = None, 1399 kind: str | None = None, 1400 lookup_key: str | None = None, 1401 path_prefix: str | None = None, 1402 parents: builtins.list[str] | None = None, 1403 parent_solutions: builtins.list[str] | None = None, 1404 ) -> ConfigListResponse: 1405 """ 1406 List configs 1407 Returns all configs owned by the specified owner. Exactly one owner selector 1408 (`team`, `user`, or `agent`) must be provided. Passing an unknown or 1409 inaccessible owner returns an empty `data` array rather than an error, to 1410 avoid leaking information about which teams, users, or agents exist. 1411 Use the `kind`, `lookup_key`, `path_prefix`, `parents`, and 1412 `parent_solutions` params to narrow results. Private config kinds are always 1413 excluded from the response regardless of the viewer's permissions. 1414 Results are not paginated; all matching configs are returned in a single 1415 response. 1416 1417 Args: 1418 team: Team ID (`team_...`) whose configs to list. Mutually exclusive with `user` and `agent`. 1419 user: User ID (`usr_...`) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive with `team` and `agent`. 1420 agent: Agent ID (`agt_...`) whose configs to list. Mutually exclusive with `team` and `user`. 1421 kind: Filter results to configs of this kind, e.g. `"Agent"` or `"APITool"`. Omit to return configs of all non-private kinds. 1422 lookup_key: Filter to the config with exactly this `lookup_key`. Returns at most one result. 1423 path_prefix: Filter to configs whose `virtual_path` starts with this prefix, e.g. `"my-agent/"`. Useful for listing files within a folder. 1424 parents: Filter to configs that are children of any of the listed parent config IDs (`cfg_...`). Pass a single ID to retrieve all children of one bundle. 1425 parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (`cfg_...`). Useful for identifying all files that arrived with a given solution. 1426 1427 Returns: 1428 Successful response 1429 """ 1430 query: dict[str, object] = {} 1431 if team is not None: 1432 query["team"] = team 1433 if user is not None: 1434 query["user"] = user 1435 if agent is not None: 1436 query["agent"] = agent 1437 if kind is not None: 1438 query["kind"] = kind 1439 if lookup_key is not None: 1440 query["lookup_key"] = lookup_key 1441 if path_prefix is not None: 1442 query["path_prefix"] = path_prefix 1443 if parents is not None: 1444 query["parents"] = parents 1445 if parent_solutions is not None: 1446 query["parent_solutions"] = parent_solutions 1447 return self._http.request("/api/v1/config", query=query, response_type=ConfigListResponse) 1448 1449 def create(self, input: ConfigCreateInput) -> Config: 1450 """ 1451 Create a config 1452 Creates a new config and its first version. Returns 201 on success. 1453 A config is uniquely identified within an app + org scope by its 1454 `virtual_path` or `lookup_key`. Creating a config at a path that already 1455 exists (including archived configs) returns 409. To adopt an existing config 1456 at that path and re-own it instead, pass `take_ownership: true` this 1457 requires modify rights on the existing row (developer or all-powerful viewer). 1458 The owner is resolved from the explicit selector params (`team`, `user`, 1459 `agent`, or `system`). Developer and all-powerful viewers default to system 1460 ownership when no explicit selector is provided. Exactly one owner selector 1461 may be set; conflicting selectors return 422. 1462 Requires app scope. 1463 1464 Args: 1465 input: Request body. 1466 input.agent: Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`. 1467 input.change_description: Human-readable description of this initial version, stored on the version record. 1468 input.data: Arbitrary key-value metadata stored on the version alongside the content. 1469 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1470 input.kind: Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`. 1471 input.lookup_key: Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners. 1472 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. 1473 input.org: Organization ID (`org_...`) to scope the config to a specific org. 1474 input.parent: Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config. 1475 input.parent_solution: Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. 1476 input.raw_content: Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text. 1477 input.relative_path: Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set. 1478 input.system: Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`. 1479 input.take_ownership: When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). 1480 input.team: Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`. 1481 input.user: User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`. 1482 input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination. 1483 1484 Returns: 1485 The newly created config, including its first version. 1486 """ 1487 return self._http.request( 1488 "/api/v1/config", 1489 method="POST", 1490 body=input, 1491 response_type=Config, 1492 ) 1493 1494 def encrypt_secret(self, input: ConfigEncryptSecretInput) -> ConfigEncryptSecretResponse: 1495 """ 1496 Encrypt a secret for use in a config 1497 Encrypts a plaintext secret and returns a ciphertext string safe for 1498 embedding directly in config content using the `secret_value!` interpolation 1499 syntax. The ciphertext is bound to the app's (or org's) key-encryption key 1500 (KEK) so it can only be decrypted at runtime within the same scope. 1501 When `org` is provided, the KEK for that org is used; otherwise the 1502 viewer's own org KEK is used, falling back to the app-level KEK for viewers 1503 with no org context. 1504 The plaintext is never stored. Requires app scope. 1505 1506 Args: 1507 input: Request body. 1508 input.org: Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. 1509 input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned. 1510 1511 Returns: 1512 Successful response 1513 """ 1514 return self._http.request( 1515 "/api/v1/config/encrypt_secret", 1516 method="POST", 1517 body=input, 1518 response_type=ConfigEncryptSecretResponse, 1519 ) 1520 1521 def facets( 1522 self, 1523 *, 1524 app: str | None = None, 1525 team: str | None = None, 1526 user: str | None = None, 1527 org: str | None = None, 1528 ) -> ConfigFacets: 1529 """ 1530 List config facets 1531 Returns the distinct config kinds and leading `virtual_path` prefixes 1532 available to the viewer, each with a count of matching configs. Use this 1533 to populate filter UI dropdowns without making a full list request. 1534 The counts reflect every config the viewer can see in the requested scope, 1535 independent of any kind, path-prefix, or lookup-key filters that might be 1536 applied on a concurrent list request. This means the UI always shows every 1537 option the viewer could pick, not just the values on the current filtered page. 1538 Scoping follows the same rules as the list endpoint: developer and 1539 all-powerful viewers see facets across all owners in the app; org-scoped 1540 viewers receive their own configs' facets merged with system-owned facets; 1541 all other viewers see only their resolved owner's configs. 1542 1543 Args: 1544 app: App ID (`app_...`). Present when mounted under the developer scope; injected automatically. 1545 team: Team ID (`team_...`) to scope facets to that team's configs. Mutually exclusive with `user`. 1546 user: User ID (`usr_...`) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive with `team`. 1547 org: Organization ID (`org_...`) to narrow facets to configs belonging to that org. 1548 1549 Returns: 1550 Distinct config kinds and `virtual_path` prefixes with per-value counts. 1551 """ 1552 query: dict[str, object] = {} 1553 if app is not None: 1554 query["app"] = app 1555 if team is not None: 1556 query["team"] = team 1557 if user is not None: 1558 query["user"] = user 1559 if org is not None: 1560 query["org"] = org 1561 return self._http.request("/api/v1/config/facets", query=query, response_type=ConfigFacets) 1562 1563 def validate(self, input: ConfigValidateInput) -> ValidationResult: 1564 """ 1565 Validate config content 1566 Validates raw config content against the schema for a given config kind 1567 without saving anything. Returns a structured result indicating whether the 1568 content is valid and, if not, a list of error messages. 1569 Use this endpoint to give users early feedback before calling create or 1570 update. The owner context is used for any kind-specific validation rules that 1571 are owner-aware; provide the same owner you intend to use on the write call. 1572 Requires app scope. 1573 1574 Args: 1575 input: Request body. 1576 input.agent: Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`. 1577 input.data: Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content. 1578 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1579 input.kind: Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`. 1580 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation. 1581 input.raw_content: Raw content bytes to validate. Parsed according to `mime_type` before schema validation. 1582 input.team: Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`. 1583 input.user: User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`. 1584 1585 Returns: 1586 Validation outcome. Always HTTP 200; check the `valid` field to determine success. Includes `errors` when `valid` is `false`. 1587 """ 1588 return self._http.request( 1589 "/api/v1/config/validate", 1590 method="POST", 1591 body=input, 1592 response_type=ValidationResult, 1593 ) 1594 1595 def delete(self, config: str) -> None: 1596 """ 1597 Delete a config 1598 Permanently deletes a config and all its associated versions. This action is 1599 irreversible. To soft-delete a config while retaining its history, use the 1600 archive endpoint instead. 1601 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1602 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1603 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1604 passing an owner selector when addressing by ID returns 422. 1605 Returns 204 No Content on success. Requires app scope. The viewer must have 1606 modify rights on the config. 1607 1608 Args: 1609 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1610 1611 Returns: 1612 Empty body. HTTP 204 indicates the config and all its versions were permanently deleted. 1613 """ 1614 self._http.request(f"/api/v1/config/{config}", method="DELETE") 1615 1616 def get( 1617 self, 1618 config: str, 1619 *, 1620 team: str | None = None, 1621 user: str | None = None, 1622 agent: str | None = None, 1623 system: bool | None = None, 1624 org: str | None = None, 1625 ) -> Config: 1626 """ 1627 Retrieve a config 1628 Returns a single config identified by its ID, `virtual_path`, or 1629 `lookup_key`. The config object includes its current version metadata but 1630 not the raw content bytes; use the content endpoint to fetch the raw content. 1631 When addressing by `lookup_key` or `virtual_path`, you must supply exactly 1632 one owner selector (`team`, `user`, `agent`, or `system`). Passing an owner 1633 selector when addressing by ID (`cfg_...`) returns 422. Both `not_found` 1634 and `forbidden` outcomes are surfaced as 404 to avoid leaking config 1635 existence. 1636 Requires app scope. 1637 1638 Args: 1639 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1640 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1641 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1642 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1643 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1644 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1645 1646 Returns: 1647 The requested config object. 1648 """ 1649 query: dict[str, object] = {} 1650 if team is not None: 1651 query["team"] = team 1652 if user is not None: 1653 query["user"] = user 1654 if agent is not None: 1655 query["agent"] = agent 1656 if system is not None: 1657 query["system"] = system 1658 if org is not None: 1659 query["org"] = org 1660 return self._http.request(f"/api/v1/config/{config}", query=query, response_type=Config) 1661 1662 def update(self, config: str, input: ConfigUpdateInput) -> Config: 1663 """ 1664 Update a config 1665 Updates an existing config. When `raw_content` is provided, a new version is 1666 created and becomes the current version. When `raw_content` is omitted, only 1667 metadata fields (`virtual_path`, `lookup_key`, `relative_path`, 1668 `parent_solution`) are updated without creating a new version. 1669 Use `expected_version` for optimistic concurrency control: if the config's 1670 current version number does not match the supplied value the request returns 1671 409. This prevents overwriting concurrent edits. 1672 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1673 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1674 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1675 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1676 Requires app scope. The viewer must have modify rights on the config. 1677 1678 Args: 1679 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1680 input: Request body. 1681 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1682 input.change_description: Human-readable description of this update, stored on the new version record. 1683 input.data: Arbitrary key-value metadata to store on the new version alongside the content. 1684 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1685 input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking. 1686 input.lookup_key: New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted. 1687 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field. 1688 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1689 input.parent_solution: Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string. 1690 input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version. 1691 input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`. 1692 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1693 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1694 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1695 input.virtual_path: New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted. 1696 1697 Returns: 1698 The config reflecting the applied update. 1699 """ 1700 return self._http.request( 1701 f"/api/v1/config/{config}", 1702 method="PATCH", 1703 body=input, 1704 response_type=Config, 1705 ) 1706 1707 def archive(self, config: str, input: ConfigArchiveInput) -> Config: 1708 """ 1709 Archive a config 1710 Soft-deletes a config by marking it as archived. Archived configs are hidden 1711 from list and show endpoints but are not permanently removed; use the 1712 unarchive endpoint to restore one, or the delete endpoint for permanent 1713 removal. 1714 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1715 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1716 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1717 passing an owner selector when addressing by ID returns 422. 1718 Requires app scope. The viewer must have modify rights on the config. 1719 1720 Args: 1721 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. `virtual_path` values should be URL-encoded if they contain slashes. 1722 input: Request body. 1723 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1724 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. 1725 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1726 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1727 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1728 1729 Returns: 1730 The config in its newly archived state. 1731 """ 1732 return self._http.request( 1733 f"/api/v1/config/{config}/archive", 1734 method="POST", 1735 body=input, 1736 response_type=Config, 1737 ) 1738 1739 def change_owner(self, config: str, input: ConfigChangeOwnerInput) -> Config: 1740 """ 1741 Transfer ownership of a config 1742 Transfers a config to a new owner (`team`, `user`, `agent`, or `system`). 1743 Exactly one of the new-owner selectors must be provided. The config must be 1744 addressed by its ID (`cfg_...` or UUID); `virtual_path` and `lookup_key` 1745 are not accepted to avoid ambiguity look up the ID first if needed. 1746 For non-system targets the new owner's org is derived automatically from the 1747 target entity; supplying `org` in that case returns 422. For `system:true` 1748 targets, `org` controls the resulting org scope: omit to keep the existing 1749 `org_id`, supply a value to set a specific org, or pass `null`/blank to make 1750 the config app-level (operator viewers only). 1751 Operator viewers (developer credentials or all-powerful viewers) may transfer 1752 to any owner. All other viewers are restricted to owners they can themselves 1753 access (team membership, user identity, agent scope, or `system` with the 1754 appropriate privilege). 1755 Requires app scope. The viewer must have modify rights on the config. 1756 1757 Args: 1758 config: Config ID in id-form: `cfg_...` or a UUID. `lookup_key` and `virtual_path` are not accepted retrieve the config ID first if you only have a path. 1759 input: Request body. 1760 input.agent: New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`. 1761 input.org: Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422. 1762 input.system: Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`. 1763 input.team: New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`. 1764 input.user: New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`. 1765 1766 Returns: 1767 The config reflecting its new ownership. 1768 """ 1769 return self._http.request( 1770 f"/api/v1/config/{config}/change_owner", 1771 method="POST", 1772 body=input, 1773 response_type=Config, 1774 ) 1775 1776 def content( 1777 self, 1778 config: str, 1779 *, 1780 team: str | None = None, 1781 user: str | None = None, 1782 agent: str | None = None, 1783 system: bool | None = None, 1784 org: str | None = None, 1785 format: str | None = None, 1786 inject_protected_fields: bool | None = None, 1787 ) -> dict[str, str]: 1788 """ 1789 Retrieve a config's raw content 1790 Returns the raw byte content of a config's current version. The response 1791 `Content-Type` header reflects the config's stored MIME type unless a 1792 `format` conversion is requested. 1793 Pass `format: "yaml"` or `format: "json"` to convert between YAML and JSON 1794 on the fly. Conversion is only supported between these two formats; requesting 1795 a conversion that is not possible returns 400. 1796 By default, `virtual_path` and other platform-injected protected fields are 1797 embedded in the returned content. Set `inject_protected_fields: false` to 1798 return the stored raw bytes exactly as written. 1799 The config may be addressed by ID (`cfg_...`), `virtual_path`, or 1800 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, exactly one 1801 owner selector (`team`, `user`, `agent`, or `system`) is required. 1802 1803 Args: 1804 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1805 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1806 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1807 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1808 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1809 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1810 format: Output format for content conversion. One of `"yaml"` or `"json"`. Omit to return the content in its stored format. Returns 400 if conversion is not possible. 1811 inject_protected_fields: Whether to inject platform-managed protected fields (such as `virtual_path`) into the returned content. Defaults to `true`. Set to `false` to receive the raw stored bytes. 1812 1813 Returns: 1814 Raw config content in the stored or requested format. 1815 """ 1816 query: dict[str, object] = {} 1817 if team is not None: 1818 query["team"] = team 1819 if user is not None: 1820 query["user"] = user 1821 if agent is not None: 1822 query["agent"] = agent 1823 if system is not None: 1824 query["system"] = system 1825 if org is not None: 1826 query["org"] = org 1827 if format is not None: 1828 query["format"] = format 1829 if inject_protected_fields is not None: 1830 query["inject_protected_fields"] = inject_protected_fields 1831 return self._http.request_raw(f"/api/v1/config/{config}/content", query=query) 1832 1833 def unarchive(self, config: str, input: ConfigUnarchiveInput) -> Config: 1834 """ 1835 Unarchive a config 1836 Restores a previously archived config, making it visible again in list and 1837 show responses. The config's content and version history are unchanged. 1838 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1839 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1840 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1841 passing an owner selector when addressing by ID returns 422. 1842 Requires app scope. The viewer must have modify rights on the config. 1843 1844 Args: 1845 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1846 input: Request body. 1847 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1848 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1849 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1850 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1851 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1852 1853 Returns: 1854 The config in its newly restored (active) state. 1855 """ 1856 return self._http.request( 1857 f"/api/v1/config/{config}/unarchive", 1858 method="POST", 1859 body=input, 1860 response_type=Config, 1861 ) 1862 1863 def versions( 1864 self, 1865 config: str, 1866 *, 1867 team: str | None = None, 1868 user: str | None = None, 1869 agent: str | None = None, 1870 system: bool | None = None, 1871 org: str | None = None, 1872 ) -> ConfigVersionsResponse: 1873 """ 1874 List a config's version history 1875 Returns all versions of a config in the order they were created, most recent 1876 first. Each version includes its version number, content metadata, and change 1877 description. The raw content bytes for a specific version are not included; 1878 use the content endpoint to fetch them. 1879 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1880 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1881 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1882 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1883 Requires app scope. 1884 1885 Args: 1886 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1887 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1888 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1889 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1890 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1891 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1892 1893 Returns: 1894 Successful response 1895 """ 1896 query: dict[str, object] = {} 1897 if team is not None: 1898 query["team"] = team 1899 if user is not None: 1900 query["user"] = user 1901 if agent is not None: 1902 query["agent"] = agent 1903 if system is not None: 1904 query["system"] = system 1905 if org is not None: 1906 query["org"] = org 1907 return self._http.request( 1908 f"/api/v1/config/{config}/versions", 1909 query=query, 1910 response_type=ConfigVersionsResponse, 1911 )
class
SystemCloneInput(typing.TypedDict):
19class SystemCloneInput(TypedDict, total=False): 20 "Clone a system config" 21 22 lookup_key: str | None 23 "Override the `lookup_key` on the cloned config. When omitted, the source value is used." 24 org: str | None 25 "Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org." 26 team: str | None 27 "Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped." 28 user: str | None 29 "User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped." 30 virtual_path: str | None 31 "Override the `virtual_path` on the cloned config. When omitted, the source value is used."
Clone a system config
lookup_key: str | None
Override the lookup_key on the cloned config. When omitted, the source value is used.
org: str | None
Organization ID (org_...) to scope the clone to. When set, must match the authenticated viewer's org.
team: str | None
Team ID (tea_...) that will own the cloned config. Required unless user is provided or the caller is app-scoped.
user: str | None
User ID (usr_...) that will own the cloned config. Required unless team is provided or the caller is app-scoped.
virtual_path: str | None
Override the virtual_path on the cloned config. When omitted, the source value is used.
class
ConfigCreateInput(typing.TypedDict):
34class ConfigCreateInput(TypedDict, total=False): 35 "Create a config" 36 37 agent: str | None 38 "Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`." 39 change_description: str | None 40 "Human-readable description of this initial version, stored on the version record." 41 data: dict[str, Any] | None 42 "Arbitrary key-value metadata stored on the version alongside the content." 43 data_encoding: str | None 44 'Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON.' 45 kind: Required[str] 46 'Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`.' 47 lookup_key: str | None 48 "Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners." 49 mime_type: Required[str] 50 'MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`.' 51 org: str | None 52 "Organization ID (`org_...`) to scope the config to a specific org." 53 parent: str | None 54 "Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config." 55 parent_solution: str | None 56 "Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle." 57 raw_content: Required[str] 58 "Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text." 59 relative_path: str | None 60 'Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set.' 61 system: bool | None 62 "Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`." 63 take_ownership: bool | None 64 "When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer)." 65 team: str | None 66 "Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`." 67 user: str | None 68 "User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`." 69 virtual_path: str | None 70 'Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination.'
Create a config
change_description: str | None
Human-readable description of this initial version, stored on the version record.
data: dict[str, typing.Any] | None
Arbitrary key-value metadata stored on the version alongside the content.
data_encoding: str | None
Encoding of raw_content. Omit or set "raw" for literal content; set "base64" when sending binary content such as images or PDFs in JSON.
kind: Required[str]
Config kind that determines the schema and behavior of the config, e.g. "Agent" or "APITool".
lookup_key: str | None
Optional stable key for looking up this config independent of its virtual_path. Must be unique within the app + org scope across all owners.
parent: str | None
Parent config ID (cfg_...) for bundle children, e.g. files belonging to a Skill. Required together with relative_path when creating a child config.
parent_solution: str | None
Solution config ID (cfg_...) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle.
raw_content: Required[str]
Raw content bytes for the first version. Accepted formats depend on mime_type; typical values are YAML or JSON text.
relative_path: str | None
Path of this config within its parent bundle, e.g. "prompts/system.md". Required when parent is set.
take_ownership: bool | None
When true and a config already exists at the specified virtual_path or lookup_key under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer).
class
ConfigEncryptSecretInput(typing.TypedDict):
73class ConfigEncryptSecretInput(TypedDict, total=False): 74 "Encrypt a secret for use in a config" 75 76 org: str | None 77 "Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context." 78 plaintext: Required[str] 79 "The secret value to encrypt. Never stored; only the resulting ciphertext is returned."
Encrypt a secret for use in a config
class
ConfigValidateInput(typing.TypedDict):
82class ConfigValidateInput(TypedDict, total=False): 83 "Validate config content" 84 85 agent: str | None 86 "Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`." 87 data: dict[str, Any] | None 88 "Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content." 89 data_encoding: str | None 90 'Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON.' 91 kind: Required[str] 92 'Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`.' 93 mime_type: Required[str] 94 'MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation.' 95 raw_content: Required[str] 96 "Raw content bytes to validate. Parsed according to `mime_type` before schema validation." 97 team: str | None 98 "Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`." 99 user: str | None 100 "User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`."
Validate config content
data: dict[str, typing.Any] | None
Optional metadata used by kind-specific validation. File and Image configs require data.name when validating direct binary content.
data_encoding: str | None
Encoding of raw_content. Omit or set "raw" for literal content; set "base64" when sending binary content such as images or PDFs in JSON.
kind: Required[str]
Config kind whose schema the content is validated against, e.g. "Agent" or "APITool".
mime_type: Required[str]
MIME type of raw_content, e.g. "application/x-yaml" or "application/json". Used to parse the content before validation.
raw_content: Required[str]
Raw content bytes to validate. Parsed according to mime_type before schema validation.
class
ConfigUpdateInput(typing.TypedDict):
103class ConfigUpdateInput(TypedDict, total=False): 104 "Update a config" 105 106 agent: str | None 107 "Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 108 change_description: str | None 109 "Human-readable description of this update, stored on the new version record." 110 data: dict[str, Any] | None 111 "Arbitrary key-value metadata to store on the new version alongside the content." 112 data_encoding: str | None 113 'Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON.' 114 expected_version: int | None 115 "Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking." 116 lookup_key: str | None 117 "New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted." 118 mime_type: str | None 119 'MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field.' 120 org: str | None 121 "Organization ID (`org_...`) to narrow the lookup to configs belonging to that org." 122 parent_solution: str | None 123 "Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string." 124 raw_content: str | None 125 "New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version." 126 relative_path: str | None 127 "Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`." 128 system: bool | None 129 "Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin." 130 team: str | None 131 "Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 132 user: str | None 133 "User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 134 virtual_path: str | None 135 "New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted."
Update a config
agent: str | None
Agent ID (agt_...) to use as the owner when resolving by virtual_path or lookup_key.
change_description: str | None
Human-readable description of this update, stored on the new version record.
data: dict[str, typing.Any] | None
Arbitrary key-value metadata to store on the new version alongside the content.
data_encoding: str | None
Encoding of raw_content. Omit or set "raw" for literal content; set "base64" when sending binary content such as images or PDFs in JSON.
expected_version: int | None
Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking.
lookup_key: str | None
New lookup_key for the config. Updates the key without creating a new version when raw_content is omitted.
mime_type: str | None
MIME type of raw_content, e.g. "application/x-yaml" or "application/json". Defaults to the existing MIME type when raw_content is provided without this field.
parent_solution: str | None
Solution config ID (cfg_...) to set as the config's parent solution provenance. Clears the value when set to an empty string.
raw_content: str | None
New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version.
relative_path: str | None
Updated path of this config within its parent bundle. Only meaningful when the config has a parent.
system: bool | None
Set true to resolve a system-owned config by virtual_path or lookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin.
team: str | None
Team ID (team_...) to use as the owner when resolving by virtual_path or lookup_key.
user: str | None
User ID (usr_...) to use as the owner when resolving by virtual_path or lookup_key.
virtual_path: str | None
New virtual_path for the config. Updates the path without creating a new version when raw_content is omitted.
class
ConfigArchiveInput(typing.TypedDict):
138class ConfigArchiveInput(TypedDict, total=False): 139 "Archive a config" 140 141 agent: str | None 142 "Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 143 org: str | None 144 "Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs." 145 system: bool | None 146 "Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin." 147 team: str | None 148 "Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 149 user: str | None 150 "User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`."
Archive a config
agent: str | None
Agent ID (agt_...) to use as the owner when resolving by virtual_path or lookup_key.
org: str | None
Organization ID (org_...) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs.
system: bool | None
Set true to resolve a system-owned config by virtual_path or lookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin.
class
ConfigChangeOwnerInput(typing.TypedDict):
153class ConfigChangeOwnerInput(TypedDict, total=False): 154 "Transfer ownership of a config" 155 156 agent: str | None 157 "New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`." 158 org: str | None 159 "Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422." 160 system: bool | None 161 "Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`." 162 team: str | None 163 "New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`." 164 user: str | None 165 "New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`."
Transfer ownership of a config
class
ConfigUnarchiveInput(typing.TypedDict):
168class ConfigUnarchiveInput(TypedDict, total=False): 169 "Unarchive a config" 170 171 agent: str | None 172 "Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 173 org: str | None 174 "Organization ID (`org_...`) to narrow the lookup to configs belonging to that org." 175 system: bool | None 176 "Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin." 177 team: str | None 178 "Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`." 179 user: str | None 180 "User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`."
Unarchive a config
agent: str | None
Agent ID (agt_...) to use as the owner when resolving by virtual_path or lookup_key.
system: bool | None
Set true to resolve a system-owned config by virtual_path or lookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin.
class
KindListResponseDataItem(pydantic.main.BaseModel):
183class KindListResponseDataItem(BaseModel): 184 classification: str = Field( 185 ..., 186 description='Structural role of this kind. `"root"` kinds are standalone configs; `"supplemental"` kinds extend or augment a root config.', 187 ) 188 description: str | None = Field( 189 default=None, 190 description="Markdown prose describing what this config kind represents and how to use it. `null` when no description has been registered for this kind.", 191 ) 192 kind: str = Field( 193 ..., 194 description='The config kind identifier (e.g., `"Agent"`, `"APITool"`). Used as the `kind` value when creating or filtering configs.', 195 ) 196 sample_available: bool = Field( 197 ..., 198 description="`true` when a sample YAML document is available for this kind via the schema endpoint.", 199 ) 200 schema_available: bool = Field( 201 ..., 202 description="`true` when a JSON Schema definition is available for this kind via the schema endpoint.", 203 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
classification: str =
PydanticUndefined
Structural role of this kind. "root" kinds are standalone configs; "supplemental" kinds extend or augment a root config.
description: str | None =
None
Markdown prose describing what this config kind represents and how to use it. null when no description has been registered for this kind.
kind: str =
PydanticUndefined
The config kind identifier (e.g., "Agent", "APITool"). Used as the kind value when creating or filtering configs.
class
KindListResponse(pydantic.main.BaseModel):
206class KindListResponse(BaseModel): 207 """ 208 Successful response 209 """ 210 211 data: list[KindListResponseDataItem] = Field( 212 ..., description="Array of config kind objects, sorted alphabetically by `kind` name." 213 )
Successful response
class
SystemListResponseDataItemCurrentVersion(pydantic.main.BaseModel):
216class SystemListResponseDataItemCurrentVersion(BaseModel): 217 change_description: str | None = Field( 218 default=None, 219 description="Human-readable summary of what changed in this version, as provided by the author. `null` if no description was supplied.", 220 ) 221 content_hash: str | None = Field( 222 default=None, 223 description="SHA-256 digest of the raw config content encoded as `sha256:<hex>`. Uses the same algorithm as the CLI `computeContentHash` helper. `null` for versions created before this field was introduced.", 224 ) 225 created_at: datetime | None = Field( 226 default=None, description="When this config version was created (ISO 8601)." 227 ) 228 data: dict[str, Any] | None = Field( 229 default=None, 230 description="Arbitrary structured metadata stored alongside this version. `null` when no extra data was provided.", 231 ) 232 id: str = Field(..., description="Config version ID (`cfv_...`).") 233 org: str | None = Field( 234 default=None, 235 description="Organization ID (`org_...`) that owns this config version. `null` for personal configs.", 236 ) 237 sandbox: str | None = Field( 238 default=None, 239 description="Sandbox ID (`sbx_...`) this version was saved under. `null` for production configs.", 240 ) 241 source_solution_config_version: str | None = Field( 242 default=None, 243 description="Config version ID (`cfv_...`) for the Solution version this config version was installed from. `null` for standalone configs and legacy rows.", 244 ) 245 version_number: int = Field( 246 ..., 247 description="Monotonically increasing integer identifying this version within the config. Starts at 1.", 248 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
change_description: str | None =
None
Human-readable summary of what changed in this version, as provided by the author. null if no description was supplied.
content_hash: str | None =
None
SHA-256 digest of the raw config content encoded as sha256:<hex>. Uses the same algorithm as the CLI computeContentHash helper. null for versions created before this field was introduced.
data: dict[str, typing.Any] | None =
None
Arbitrary structured metadata stored alongside this version. null when no extra data was provided.
org: str | None =
None
Organization ID (org_...) that owns this config version. null for personal configs.
sandbox: str | None =
None
Sandbox ID (sbx_...) this version was saved under. null for production configs.
class
SystemListResponseDataItem(pydantic.main.BaseModel):
251class SystemListResponseDataItem(BaseModel): 252 agent: str | None = Field( 253 default=None, 254 description="Agent ID (`agt_...`) associated with this config. `null` if not linked to an agent.", 255 ) 256 created_at: datetime | None = Field( 257 default=None, description="When this config was first created (ISO 8601)." 258 ) 259 current_version: SystemListResponseDataItemCurrentVersion | None = Field( 260 default=None, 261 description="The most recently saved version of this config. `null` if the config has never been saved with content.", 262 ) 263 id: str = Field(..., description="Config ID (`cfg_...`).") 264 is_archived: bool | None = Field( 265 default=None, 266 description="Whether this config has been archived. Archived configs are hidden from default listings but remain accessible by ID.", 267 ) 268 kind: str = Field( 269 ..., 270 description='Type of config, e.g. `"Agent"` or `"APITool"`. Determines which fields and validation rules apply.', 271 ) 272 lookup_key: str | None = Field( 273 default=None, 274 description="Stable, user-defined key used to look up this config without knowing its ID. `null` if not set.", 275 ) 276 mime_type: str | None = Field( 277 default=None, 278 description='MIME type of the config\'s content, e.g. `"text/yaml"`. `null` if not determined.', 279 ) 280 org: str | None = Field( 281 default=None, 282 description="Organization ID (`org_...`) this config belongs to. `null` for configs not scoped to an org.", 283 ) 284 parent: str | None = Field( 285 default=None, 286 description="Parent bundle config ID (`cfg_...`). Present only for configs that are children of a bundle; `null` otherwise.", 287 ) 288 parent_solution: str | None = Field( 289 default=None, 290 description="ID (`cfg_...`) of the solution config this config was imported with. `null` if the config was not imported via a solution.", 291 ) 292 raw_content: str | None = Field( 293 default=None, 294 description="Raw file content as a string. Populated only for system configs; `null` for user-owned configs.", 295 ) 296 relative_path: str | None = Field( 297 default=None, 298 description="Path of this config relative to its parent bundle root. Present only for bundle children; `null` otherwise.", 299 ) 300 sandbox: str | None = Field( 301 default=None, 302 description="Sandbox identifier this config belongs to. `null` for production configs.", 303 ) 304 team: str | None = Field( 305 default=None, 306 description="Team ID (`tea_...`) that owns this config. `null` for personal (user-scoped) configs.", 307 ) 308 updated_at: datetime | None = Field( 309 default=None, description="When this config was last modified (ISO 8601)." 310 ) 311 user: str | None = Field( 312 default=None, 313 description="User ID (`usr_...`) who owns this config. `null` for team-scoped configs.", 314 ) 315 virtual_path: str | None = Field( 316 default=None, 317 description='Logical path uniquely identifying this config within its team, e.g. `"agents/my-agent.yaml"`. `null` for configs without an explicit path.', 318 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
Agent ID (agt_...) associated with this config. null if not linked to an agent.
The most recently saved version of this config. null if the config has never been saved with content.
is_archived: bool | None =
None
Whether this config has been archived. Archived configs are hidden from default listings but remain accessible by ID.
kind: str =
PydanticUndefined
Type of config, e.g. "Agent" or "APITool". Determines which fields and validation rules apply.
lookup_key: str | None =
None
Stable, user-defined key used to look up this config without knowing its ID. null if not set.
mime_type: str | None =
None
MIME type of the config's content, e.g. "text/yaml". null if not determined.
org: str | None =
None
Organization ID (org_...) this config belongs to. null for configs not scoped to an org.
parent: str | None =
None
Parent bundle config ID (cfg_...). Present only for configs that are children of a bundle; null otherwise.
parent_solution: str | None =
None
ID (cfg_...) of the solution config this config was imported with. null if the config was not imported via a solution.
raw_content: str | None =
None
Raw file content as a string. Populated only for system configs; null for user-owned configs.
relative_path: str | None =
None
Path of this config relative to its parent bundle root. Present only for bundle children; null otherwise.
class
SystemListResponse(pydantic.main.BaseModel):
321class SystemListResponse(BaseModel): 322 """ 323 Successful response 324 """ 325 326 data: list[SystemListResponseDataItem] = Field( 327 ..., description="Array of system config objects for the current page." 328 ) 329 has_next: bool = Field(..., description="`true` when a subsequent page of results exists.") 330 has_prev: bool = Field(..., description="`true` when a previous page of results exists.") 331 page: int = Field(..., description="The current page number (1-indexed).") 332 page_size: int = Field(..., description="Number of results returned per page.") 333 total_entries: int = Field( 334 ..., 335 description="Total number of system configs matching the applied filters across all pages.", 336 ) 337 total_pages: int = Field( 338 ..., description="Total number of pages given the current `page_size`." 339 )
Successful response
class
ConfigListResponseDataItemCurrentVersion(pydantic.main.BaseModel):
342class ConfigListResponseDataItemCurrentVersion(BaseModel): 343 change_description: str | None = Field( 344 default=None, 345 description="Human-readable summary of what changed in this version, as provided by the author. `null` if no description was supplied.", 346 ) 347 content_hash: str | None = Field( 348 default=None, 349 description="SHA-256 digest of the raw config content encoded as `sha256:<hex>`. Uses the same algorithm as the CLI `computeContentHash` helper. `null` for versions created before this field was introduced.", 350 ) 351 created_at: datetime | None = Field( 352 default=None, description="When this config version was created (ISO 8601)." 353 ) 354 data: dict[str, Any] | None = Field( 355 default=None, 356 description="Arbitrary structured metadata stored alongside this version. `null` when no extra data was provided.", 357 ) 358 id: str = Field(..., description="Config version ID (`cfv_...`).") 359 org: str | None = Field( 360 default=None, 361 description="Organization ID (`org_...`) that owns this config version. `null` for personal configs.", 362 ) 363 sandbox: str | None = Field( 364 default=None, 365 description="Sandbox ID (`sbx_...`) this version was saved under. `null` for production configs.", 366 ) 367 source_solution_config_version: str | None = Field( 368 default=None, 369 description="Config version ID (`cfv_...`) for the Solution version this config version was installed from. `null` for standalone configs and legacy rows.", 370 ) 371 version_number: int = Field( 372 ..., 373 description="Monotonically increasing integer identifying this version within the config. Starts at 1.", 374 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
change_description: str | None =
None
Human-readable summary of what changed in this version, as provided by the author. null if no description was supplied.
content_hash: str | None =
None
SHA-256 digest of the raw config content encoded as sha256:<hex>. Uses the same algorithm as the CLI computeContentHash helper. null for versions created before this field was introduced.
data: dict[str, typing.Any] | None =
None
Arbitrary structured metadata stored alongside this version. null when no extra data was provided.
org: str | None =
None
Organization ID (org_...) that owns this config version. null for personal configs.
sandbox: str | None =
None
Sandbox ID (sbx_...) this version was saved under. null for production configs.
class
ConfigListResponseDataItem(pydantic.main.BaseModel):
377class ConfigListResponseDataItem(BaseModel): 378 agent: str | None = Field( 379 default=None, 380 description="Agent ID (`agt_...`) associated with this config. `null` if not linked to an agent.", 381 ) 382 created_at: datetime | None = Field( 383 default=None, description="When this config was first created (ISO 8601)." 384 ) 385 current_version: ConfigListResponseDataItemCurrentVersion | None = Field( 386 default=None, 387 description="The most recently saved version of this config. `null` if the config has never been saved with content.", 388 ) 389 id: str = Field(..., description="Config ID (`cfg_...`).") 390 is_archived: bool | None = Field( 391 default=None, 392 description="Whether this config has been archived. Archived configs are hidden from default listings but remain accessible by ID.", 393 ) 394 kind: str = Field( 395 ..., 396 description='Type of config, e.g. `"Agent"` or `"APITool"`. Determines which fields and validation rules apply.', 397 ) 398 lookup_key: str | None = Field( 399 default=None, 400 description="Stable, user-defined key used to look up this config without knowing its ID. `null` if not set.", 401 ) 402 mime_type: str | None = Field( 403 default=None, 404 description='MIME type of the config\'s content, e.g. `"text/yaml"`. `null` if not determined.', 405 ) 406 org: str | None = Field( 407 default=None, 408 description="Organization ID (`org_...`) this config belongs to. `null` for configs not scoped to an org.", 409 ) 410 parent: str | None = Field( 411 default=None, 412 description="Parent bundle config ID (`cfg_...`). Present only for configs that are children of a bundle; `null` otherwise.", 413 ) 414 parent_solution: str | None = Field( 415 default=None, 416 description="ID (`cfg_...`) of the solution config this config was imported with. `null` if the config was not imported via a solution.", 417 ) 418 raw_content: str | None = Field( 419 default=None, 420 description="Raw file content as a string. Populated only for system configs; `null` for user-owned configs.", 421 ) 422 relative_path: str | None = Field( 423 default=None, 424 description="Path of this config relative to its parent bundle root. Present only for bundle children; `null` otherwise.", 425 ) 426 sandbox: str | None = Field( 427 default=None, 428 description="Sandbox identifier this config belongs to. `null` for production configs.", 429 ) 430 team: str | None = Field( 431 default=None, 432 description="Team ID (`tea_...`) that owns this config. `null` for personal (user-scoped) configs.", 433 ) 434 updated_at: datetime | None = Field( 435 default=None, description="When this config was last modified (ISO 8601)." 436 ) 437 user: str | None = Field( 438 default=None, 439 description="User ID (`usr_...`) who owns this config. `null` for team-scoped configs.", 440 ) 441 virtual_path: str | None = Field( 442 default=None, 443 description='Logical path uniquely identifying this config within its team, e.g. `"agents/my-agent.yaml"`. `null` for configs without an explicit path.', 444 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
agent: str | None =
None
Agent ID (agt_...) associated with this config. null if not linked to an agent.
The most recently saved version of this config. null if the config has never been saved with content.
is_archived: bool | None =
None
Whether this config has been archived. Archived configs are hidden from default listings but remain accessible by ID.
kind: str =
PydanticUndefined
Type of config, e.g. "Agent" or "APITool". Determines which fields and validation rules apply.
lookup_key: str | None =
None
Stable, user-defined key used to look up this config without knowing its ID. null if not set.
mime_type: str | None =
None
MIME type of the config's content, e.g. "text/yaml". null if not determined.
org: str | None =
None
Organization ID (org_...) this config belongs to. null for configs not scoped to an org.
parent: str | None =
None
Parent bundle config ID (cfg_...). Present only for configs that are children of a bundle; null otherwise.
parent_solution: str | None =
None
ID (cfg_...) of the solution config this config was imported with. null if the config was not imported via a solution.
raw_content: str | None =
None
Raw file content as a string. Populated only for system configs; null for user-owned configs.
relative_path: str | None =
None
Path of this config relative to its parent bundle root. Present only for bundle children; null otherwise.
class
ConfigListResponse(pydantic.main.BaseModel):
447class ConfigListResponse(BaseModel): 448 """ 449 Successful response 450 """ 451 452 data: list[ConfigListResponseDataItem] = Field( 453 ..., description="Array of config objects matching the query." 454 )
Successful response
class
ConfigEncryptSecretResponse(pydantic.main.BaseModel):
457class ConfigEncryptSecretResponse(BaseModel): 458 """ 459 Successful response 460 """ 461 462 encrypted_value: str = Field( 463 ..., 464 description="Encrypted ciphertext string. Embed this in config content using the `secret_value!` interpolation syntax to have it decrypted at runtime.", 465 )
Successful response
class
ConfigVersionsResponseVersionsItem(pydantic.main.BaseModel):
468class ConfigVersionsResponseVersionsItem(BaseModel): 469 change_description: str | None = Field( 470 default=None, 471 description="Human-readable summary of what changed in this version, as provided by the author. `null` if no description was supplied.", 472 ) 473 content_hash: str | None = Field( 474 default=None, 475 description="SHA-256 digest of the raw config content encoded as `sha256:<hex>`. Uses the same algorithm as the CLI `computeContentHash` helper. `null` for versions created before this field was introduced.", 476 ) 477 created_at: datetime | None = Field( 478 default=None, description="When this config version was created (ISO 8601)." 479 ) 480 data: dict[str, Any] | None = Field( 481 default=None, 482 description="Arbitrary structured metadata stored alongside this version. `null` when no extra data was provided.", 483 ) 484 id: str = Field(..., description="Config version ID (`cfv_...`).") 485 org: str | None = Field( 486 default=None, 487 description="Organization ID (`org_...`) that owns this config version. `null` for personal configs.", 488 ) 489 sandbox: str | None = Field( 490 default=None, 491 description="Sandbox ID (`sbx_...`) this version was saved under. `null` for production configs.", 492 ) 493 source_solution_config_version: str | None = Field( 494 default=None, 495 description="Config version ID (`cfv_...`) for the Solution version this config version was installed from. `null` for standalone configs and legacy rows.", 496 ) 497 version_number: int = Field( 498 ..., 499 description="Monotonically increasing integer identifying this version within the config. Starts at 1.", 500 )
!!! abstract "Usage Documentation" Models
A base class for creating Pydantic models.
Attributes:
- __class_vars__: The names of the class variables defined on the model.
- __private_attributes__: Metadata about the private attributes of the model.
- __signature__: The synthesized
__init__[Signature][inspect.Signature] of the model. - __pydantic_complete__: Whether model building is completed, or if there are still undefined fields.
- __pydantic_core_schema__: The core schema of the model.
- __pydantic_custom_init__: Whether the model has a custom
__init__function. - __pydantic_decorators__: Metadata containing the decorators defined on the model.
This replaces
Model.__validators__andModel.__root_validators__from Pydantic V1. - __pydantic_generic_metadata__: A dictionary containing metadata about generic Pydantic models.
The
originandargsitems map to the [__origin__][genericalias.__origin__] and [__args__][genericalias.__args__] attributes of [generic aliases][types-genericalias], and theparameteritem maps to the__parameter__attribute of generic classes. - __pydantic_parent_namespace__: Parent namespace of the model, used for automatic rebuilding of models.
- __pydantic_post_init__: The name of the post-init method for the model, if defined.
- __pydantic_root_model__: Whether the model is a [
RootModel][pydantic.root_model.RootModel]. - __pydantic_serializer__: The
pydantic-coreSchemaSerializerused to dump instances of the model. - __pydantic_validator__: The
pydantic-coreSchemaValidatorused to validate instances of the model. - __pydantic_fields__: A dictionary of field names and their corresponding [
FieldInfo][pydantic.fields.FieldInfo] objects. - __pydantic_computed_fields__: A dictionary of computed field names and their corresponding [
ComputedFieldInfo][pydantic.fields.ComputedFieldInfo] objects. - __pydantic_extra__: A dictionary containing extra values, if [
extra][pydantic.config.ConfigDict.extra] is set to'allow'. - __pydantic_fields_set__: The names of fields explicitly set during instantiation.
- __pydantic_private__: Values of private attributes set on the model instance.
change_description: str | None =
None
Human-readable summary of what changed in this version, as provided by the author. null if no description was supplied.
content_hash: str | None =
None
SHA-256 digest of the raw config content encoded as sha256:<hex>. Uses the same algorithm as the CLI computeContentHash helper. null for versions created before this field was introduced.
data: dict[str, typing.Any] | None =
None
Arbitrary structured metadata stored alongside this version. null when no extra data was provided.
org: str | None =
None
Organization ID (org_...) that owns this config version. null for personal configs.
sandbox: str | None =
None
Sandbox ID (sbx_...) this version was saved under. null for production configs.
class
ConfigVersionsResponse(pydantic.main.BaseModel):
503class ConfigVersionsResponse(BaseModel): 504 """ 505 Successful response 506 """ 507 508 versions: list[ConfigVersionsResponseVersionsItem] = Field( 509 ..., description="Array of version objects ordered from most recent to oldest." 510 )
Successful response
class
AsyncKindResource:
513class AsyncKindResource: 514 def __init__(self, http: HttpClient): 515 self._http = http 516 517 async def list(self, *, kind: builtins.list[str] | None = None) -> KindListResponse: 518 """ 519 List config kinds 520 Returns all config kinds registered in the platform, sorted alphabetically by name. 521 Each entry describes a type of configuration object (e.g., `"Agent"`, `"APITool"`) and 522 indicates whether a JSON schema and a YAML sample are available for it. 523 Any authenticated user may call this endpoint; no ownership scope is required. 524 Pass one or more `kind` values to restrict the response to those specific kinds. 525 Omit the parameter to receive the full list of non-private kinds. 526 527 Args: 528 kind: One or more config kind names to include in the response (e.g., `"Agent"`, `"APITool"`). Omit to return all non-private kinds. 529 530 Returns: 531 Successful response 532 """ 533 query: dict[str, object] = {} 534 if kind is not None: 535 query["kind"] = kind 536 return await self._http.request( 537 "/api/v1/config/kinds", 538 query=query, 539 response_type=KindListResponse, 540 ) 541 542 async def schema(self, kind: str) -> ConfigKindSchema: 543 """ 544 Retrieve a config kind schema 545 Returns the JSON schema and a YAML sample for a single config kind. Use this to 546 understand the structure a config object of that kind must follow before creating 547 or validating one. 548 The `json_schema` field is `null` when the kind has no machine-readable schema 549 defined. The `sample_yaml` field is `null` when no sample is available. Any 550 authenticated user may call this endpoint; no ownership scope is required. 551 Returns 404 if the kind name does not match a registered, non-private config kind. 552 553 Args: 554 kind: Name of the config kind to retrieve (e.g., `"Agent"`, `"APITool"`). Must match a registered, non-private kind exactly. 555 556 Returns: 557 The JSON schema and YAML sample for the requested config kind. 558 """ 559 return await self._http.request( 560 f"/api/v1/config/kinds/{kind}/schema", 561 response_type=ConfigKindSchema, 562 )
AsyncKindResource(http: archastro.platform.runtime.http_client.HttpClient)
517 async def list(self, *, kind: builtins.list[str] | None = None) -> KindListResponse: 518 """ 519 List config kinds 520 Returns all config kinds registered in the platform, sorted alphabetically by name. 521 Each entry describes a type of configuration object (e.g., `"Agent"`, `"APITool"`) and 522 indicates whether a JSON schema and a YAML sample are available for it. 523 Any authenticated user may call this endpoint; no ownership scope is required. 524 Pass one or more `kind` values to restrict the response to those specific kinds. 525 Omit the parameter to receive the full list of non-private kinds. 526 527 Args: 528 kind: One or more config kind names to include in the response (e.g., `"Agent"`, `"APITool"`). Omit to return all non-private kinds. 529 530 Returns: 531 Successful response 532 """ 533 query: dict[str, object] = {} 534 if kind is not None: 535 query["kind"] = kind 536 return await self._http.request( 537 "/api/v1/config/kinds", 538 query=query, 539 response_type=KindListResponse, 540 )
List config kinds
Returns all config kinds registered in the platform, sorted alphabetically by name.
Each entry describes a type of configuration object (e.g., "Agent", "APITool") and
indicates whether a JSON schema and a YAML sample are available for it.
Any authenticated user may call this endpoint; no ownership scope is required.
Pass one or more kind values to restrict the response to those specific kinds.
Omit the parameter to receive the full list of non-private kinds.
Arguments:
- kind: One or more config kind names to include in the response (e.g.,
"Agent","APITool"). Omit to return all non-private kinds.
Returns:
Successful response
542 async def schema(self, kind: str) -> ConfigKindSchema: 543 """ 544 Retrieve a config kind schema 545 Returns the JSON schema and a YAML sample for a single config kind. Use this to 546 understand the structure a config object of that kind must follow before creating 547 or validating one. 548 The `json_schema` field is `null` when the kind has no machine-readable schema 549 defined. The `sample_yaml` field is `null` when no sample is available. Any 550 authenticated user may call this endpoint; no ownership scope is required. 551 Returns 404 if the kind name does not match a registered, non-private config kind. 552 553 Args: 554 kind: Name of the config kind to retrieve (e.g., `"Agent"`, `"APITool"`). Must match a registered, non-private kind exactly. 555 556 Returns: 557 The JSON schema and YAML sample for the requested config kind. 558 """ 559 return await self._http.request( 560 f"/api/v1/config/kinds/{kind}/schema", 561 response_type=ConfigKindSchema, 562 )
Retrieve a config kind schema
Returns the JSON schema and a YAML sample for a single config kind. Use this to
understand the structure a config object of that kind must follow before creating
or validating one.
The json_schema field is null when the kind has no machine-readable schema
defined. The sample_yaml field is null when no sample is available. Any
authenticated user may call this endpoint; no ownership scope is required.
Returns 404 if the kind name does not match a registered, non-private config kind.
Arguments:
- kind: Name of the config kind to retrieve (e.g.,
"Agent","APITool"). Must match a registered, non-private kind exactly.
Returns:
The JSON schema and YAML sample for the requested config kind.
class
AsyncSystemResource:
565class AsyncSystemResource: 566 def __init__(self, http: HttpClient): 567 self._http = http 568 569 async def list( 570 self, 571 *, 572 kind: str | None = None, 573 kinds: builtins.list[str] | None = None, 574 excluded_path_prefixes: builtins.list[str] | None = None, 575 page: int | None = None, 576 page_size: int | None = None, 577 ) -> SystemListResponse: 578 """ 579 List system configs 580 Returns a paginated list of system (template) configs from the filesystem-backed 581 manifest. Results are always ordered by `virtual_path` ascending. 582 Filter by one or more config kinds using `kind` (single value) or `kinds` (array). 583 Both filters may be supplied together for backward compatibility; `kinds` takes 584 precedence when both are present. Exclude specific path namespaces with 585 `excluded_path_prefixes`. 586 Use `page` and `page_size` to paginate. Page size is clamped to a maximum of 200; 587 requests exceeding this limit are silently clamped rather than rejected. 588 589 Args: 590 kind: Filter results to a single config kind, e.g. `"Agent"` or `"APITool"`. Use `kinds` to filter by multiple kinds at once. 591 kinds: Filter results to configs whose `kind` is in this list. When both `kind` and `kinds` are provided, `kinds` takes precedence. 592 excluded_path_prefixes: Exclude configs whose `virtual_path` starts with any of the listed string prefixes. 593 page: Page number to retrieve, 1-indexed. Defaults to `1`. 594 page_size: Number of results per page. Defaults to `50`; maximum is `200`. Values above the maximum are clamped to `200`. 595 596 Returns: 597 Successful response 598 """ 599 query: dict[str, object] = {} 600 if kind is not None: 601 query["kind"] = kind 602 if kinds is not None: 603 query["kinds"] = kinds 604 if excluded_path_prefixes is not None: 605 query["excluded_path_prefixes"] = excluded_path_prefixes 606 if page is not None: 607 query["page"] = page 608 if page_size is not None: 609 query["page_size"] = page_size 610 return await self._http.request( 611 "/api/v1/config/system", 612 query=query, 613 response_type=SystemListResponse, 614 ) 615 616 async def facets(self) -> ConfigFacets: 617 """ 618 Retrieve system config facets 619 Returns the distinct `kind` values and leading `virtual_path` prefixes present 620 in the system (template) config manifest, each accompanied by a count of matching 621 configs. Use this data to populate filter UIs or to determine which config kinds 622 are available before listing or cloning. 623 The response reflects the filesystem-backed template manifest and does not include 624 user- or team-owned configs. 625 626 Returns: 627 Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs. 628 """ 629 return await self._http.request("/api/v1/config/system/facets", response_type=ConfigFacets) 630 631 async def get(self, system: str) -> Config: 632 """ 633 Retrieve a system config 634 Returns a single system (template) config identified by its `virtual_path` or 635 `lookup_key`. The `system` parameter value is URL-decoded before lookup, so 636 path segments with special characters may be passed URL-encoded. 637 System configs are filesystem-backed templates and are readable by any 638 authenticated caller regardless of team or user ownership. Returns 404 when no 639 system config matches the given identifier. 640 641 Args: 642 system: Identifier of the system config to retrieve either its `virtual_path` or its `lookup_key`. May be URL-encoded. 643 644 Returns: 645 The requested system config, including its current version and all metadata fields. 646 """ 647 return await self._http.request(f"/api/v1/config/system/{system}", response_type=Config) 648 649 async def clone(self, system: str, input: SystemCloneInput) -> Config: 650 """ 651 Clone a system config 652 Creates a copy of a system (template) config and transfers ownership to a team 653 or user. All dependencies bundled with the source config are cloned alongside it. 654 Responds with HTTP 201 and the newly created config on success. 655 You must specify exactly one destination owner via `team` or `user`. Callers 656 authenticated as an app (developer portal) may omit the owner the clone is 657 then scoped to the system owner automatically. 658 Use `virtual_path` and `lookup_key` to override the corresponding fields on the 659 clone; omitting them carries the values from the source. 660 661 Args: 662 system: Identifier of the source system config either its `virtual_path` or its `lookup_key`. 663 input: Request body. 664 input.lookup_key: Override the `lookup_key` on the cloned config. When omitted, the source value is used. 665 input.org: Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org. 666 input.team: Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped. 667 input.user: User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped. 668 input.virtual_path: Override the `virtual_path` on the cloned config. When omitted, the source value is used. 669 670 Returns: 671 The newly created config, including all cloned fields and its assigned ID. 672 """ 673 return await self._http.request( 674 f"/api/v1/config/system/{system}/clone", 675 method="POST", 676 body=input, 677 response_type=Config, 678 )
AsyncSystemResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, *, kind: str | None = None, kinds: list[str] | None = None, excluded_path_prefixes: list[str] | None = None, page: int | None = None, page_size: int | None = None) -> SystemListResponse:
569 async def list( 570 self, 571 *, 572 kind: str | None = None, 573 kinds: builtins.list[str] | None = None, 574 excluded_path_prefixes: builtins.list[str] | None = None, 575 page: int | None = None, 576 page_size: int | None = None, 577 ) -> SystemListResponse: 578 """ 579 List system configs 580 Returns a paginated list of system (template) configs from the filesystem-backed 581 manifest. Results are always ordered by `virtual_path` ascending. 582 Filter by one or more config kinds using `kind` (single value) or `kinds` (array). 583 Both filters may be supplied together for backward compatibility; `kinds` takes 584 precedence when both are present. Exclude specific path namespaces with 585 `excluded_path_prefixes`. 586 Use `page` and `page_size` to paginate. Page size is clamped to a maximum of 200; 587 requests exceeding this limit are silently clamped rather than rejected. 588 589 Args: 590 kind: Filter results to a single config kind, e.g. `"Agent"` or `"APITool"`. Use `kinds` to filter by multiple kinds at once. 591 kinds: Filter results to configs whose `kind` is in this list. When both `kind` and `kinds` are provided, `kinds` takes precedence. 592 excluded_path_prefixes: Exclude configs whose `virtual_path` starts with any of the listed string prefixes. 593 page: Page number to retrieve, 1-indexed. Defaults to `1`. 594 page_size: Number of results per page. Defaults to `50`; maximum is `200`. Values above the maximum are clamped to `200`. 595 596 Returns: 597 Successful response 598 """ 599 query: dict[str, object] = {} 600 if kind is not None: 601 query["kind"] = kind 602 if kinds is not None: 603 query["kinds"] = kinds 604 if excluded_path_prefixes is not None: 605 query["excluded_path_prefixes"] = excluded_path_prefixes 606 if page is not None: 607 query["page"] = page 608 if page_size is not None: 609 query["page_size"] = page_size 610 return await self._http.request( 611 "/api/v1/config/system", 612 query=query, 613 response_type=SystemListResponse, 614 )
List system configs
Returns a paginated list of system (template) configs from the filesystem-backed
manifest. Results are always ordered by virtual_path ascending.
Filter by one or more config kinds using kind (single value) or kinds (array).
Both filters may be supplied together for backward compatibility; kinds takes
precedence when both are present. Exclude specific path namespaces with
excluded_path_prefixes.
Use page and page_size to paginate. Page size is clamped to a maximum of 200;
requests exceeding this limit are silently clamped rather than rejected.
Arguments:
- kind: Filter results to a single config kind, e.g.
"Agent"or"APITool". Usekindsto filter by multiple kinds at once. - kinds: Filter results to configs whose
kindis in this list. When bothkindandkindsare provided,kindstakes precedence. - excluded_path_prefixes: Exclude configs whose
virtual_pathstarts with any of the listed string prefixes. - page: Page number to retrieve, 1-indexed. Defaults to
1. - page_size: Number of results per page. Defaults to
50; maximum is200. Values above the maximum are clamped to200.
Returns:
Successful response
616 async def facets(self) -> ConfigFacets: 617 """ 618 Retrieve system config facets 619 Returns the distinct `kind` values and leading `virtual_path` prefixes present 620 in the system (template) config manifest, each accompanied by a count of matching 621 configs. Use this data to populate filter UIs or to determine which config kinds 622 are available before listing or cloning. 623 The response reflects the filesystem-backed template manifest and does not include 624 user- or team-owned configs. 625 626 Returns: 627 Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs. 628 """ 629 return await self._http.request("/api/v1/config/system/facets", response_type=ConfigFacets)
Retrieve system config facets
Returns the distinct kind values and leading virtual_path prefixes present
in the system (template) config manifest, each accompanied by a count of matching
configs. Use this data to populate filter UIs or to determine which config kinds
are available before listing or cloning.
The response reflects the filesystem-backed template manifest and does not include
user- or team-owned configs.
Returns:
Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs.
631 async def get(self, system: str) -> Config: 632 """ 633 Retrieve a system config 634 Returns a single system (template) config identified by its `virtual_path` or 635 `lookup_key`. The `system` parameter value is URL-decoded before lookup, so 636 path segments with special characters may be passed URL-encoded. 637 System configs are filesystem-backed templates and are readable by any 638 authenticated caller regardless of team or user ownership. Returns 404 when no 639 system config matches the given identifier. 640 641 Args: 642 system: Identifier of the system config to retrieve either its `virtual_path` or its `lookup_key`. May be URL-encoded. 643 644 Returns: 645 The requested system config, including its current version and all metadata fields. 646 """ 647 return await self._http.request(f"/api/v1/config/system/{system}", response_type=Config)
Retrieve a system config
Returns a single system (template) config identified by its virtual_path or
lookup_key. The system parameter value is URL-decoded before lookup, so
path segments with special characters may be passed URL-encoded.
System configs are filesystem-backed templates and are readable by any
authenticated caller regardless of team or user ownership. Returns 404 when no
system config matches the given identifier.
Arguments:
- system: Identifier of the system config to retrieve either its
virtual_pathor itslookup_key. May be URL-encoded.
Returns:
The requested system config, including its current version and all metadata fields.
async def
clone( self, system: str, input: SystemCloneInput) -> archastro.platform.types.config.Config:
649 async def clone(self, system: str, input: SystemCloneInput) -> Config: 650 """ 651 Clone a system config 652 Creates a copy of a system (template) config and transfers ownership to a team 653 or user. All dependencies bundled with the source config are cloned alongside it. 654 Responds with HTTP 201 and the newly created config on success. 655 You must specify exactly one destination owner via `team` or `user`. Callers 656 authenticated as an app (developer portal) may omit the owner the clone is 657 then scoped to the system owner automatically. 658 Use `virtual_path` and `lookup_key` to override the corresponding fields on the 659 clone; omitting them carries the values from the source. 660 661 Args: 662 system: Identifier of the source system config either its `virtual_path` or its `lookup_key`. 663 input: Request body. 664 input.lookup_key: Override the `lookup_key` on the cloned config. When omitted, the source value is used. 665 input.org: Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org. 666 input.team: Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped. 667 input.user: User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped. 668 input.virtual_path: Override the `virtual_path` on the cloned config. When omitted, the source value is used. 669 670 Returns: 671 The newly created config, including all cloned fields and its assigned ID. 672 """ 673 return await self._http.request( 674 f"/api/v1/config/system/{system}/clone", 675 method="POST", 676 body=input, 677 response_type=Config, 678 )
Clone a system config
Creates a copy of a system (template) config and transfers ownership to a team
or user. All dependencies bundled with the source config are cloned alongside it.
Responds with HTTP 201 and the newly created config on success.
You must specify exactly one destination owner via team or user. Callers
authenticated as an app (developer portal) may omit the owner the clone is
then scoped to the system owner automatically.
Use virtual_path and lookup_key to override the corresponding fields on the
clone; omitting them carries the values from the source.
Arguments:
- system: Identifier of the source system config either its
virtual_pathor itslookup_key. - input: Request body.
- input.lookup_key: Override the
lookup_keyon the cloned config. When omitted, the source value is used. - input.org: Organization ID (
org_...) to scope the clone to. When set, must match the authenticated viewer's org. - input.team: Team ID (
tea_...) that will own the cloned config. Required unlessuseris provided or the caller is app-scoped. - input.user: User ID (
usr_...) that will own the cloned config. Required unlessteamis provided or the caller is app-scoped. - input.virtual_path: Override the
virtual_pathon the cloned config. When omitted, the source value is used.
Returns:
The newly created config, including all cloned fields and its assigned ID.
class
AsyncConfigResource:
681class AsyncConfigResource: 682 def __init__(self, http: HttpClient): 683 self._http = http 684 self.kinds = AsyncKindResource(http) 685 self.system = AsyncSystemResource(http) 686 687 async def list( 688 self, 689 *, 690 team: str | None = None, 691 user: str | None = None, 692 agent: str | None = None, 693 kind: str | None = None, 694 lookup_key: str | None = None, 695 path_prefix: str | None = None, 696 parents: builtins.list[str] | None = None, 697 parent_solutions: builtins.list[str] | None = None, 698 ) -> ConfigListResponse: 699 """ 700 List configs 701 Returns all configs owned by the specified owner. Exactly one owner selector 702 (`team`, `user`, or `agent`) must be provided. Passing an unknown or 703 inaccessible owner returns an empty `data` array rather than an error, to 704 avoid leaking information about which teams, users, or agents exist. 705 Use the `kind`, `lookup_key`, `path_prefix`, `parents`, and 706 `parent_solutions` params to narrow results. Private config kinds are always 707 excluded from the response regardless of the viewer's permissions. 708 Results are not paginated; all matching configs are returned in a single 709 response. 710 711 Args: 712 team: Team ID (`team_...`) whose configs to list. Mutually exclusive with `user` and `agent`. 713 user: User ID (`usr_...`) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive with `team` and `agent`. 714 agent: Agent ID (`agt_...`) whose configs to list. Mutually exclusive with `team` and `user`. 715 kind: Filter results to configs of this kind, e.g. `"Agent"` or `"APITool"`. Omit to return configs of all non-private kinds. 716 lookup_key: Filter to the config with exactly this `lookup_key`. Returns at most one result. 717 path_prefix: Filter to configs whose `virtual_path` starts with this prefix, e.g. `"my-agent/"`. Useful for listing files within a folder. 718 parents: Filter to configs that are children of any of the listed parent config IDs (`cfg_...`). Pass a single ID to retrieve all children of one bundle. 719 parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (`cfg_...`). Useful for identifying all files that arrived with a given solution. 720 721 Returns: 722 Successful response 723 """ 724 query: dict[str, object] = {} 725 if team is not None: 726 query["team"] = team 727 if user is not None: 728 query["user"] = user 729 if agent is not None: 730 query["agent"] = agent 731 if kind is not None: 732 query["kind"] = kind 733 if lookup_key is not None: 734 query["lookup_key"] = lookup_key 735 if path_prefix is not None: 736 query["path_prefix"] = path_prefix 737 if parents is not None: 738 query["parents"] = parents 739 if parent_solutions is not None: 740 query["parent_solutions"] = parent_solutions 741 return await self._http.request( 742 "/api/v1/config", 743 query=query, 744 response_type=ConfigListResponse, 745 ) 746 747 async def create(self, input: ConfigCreateInput) -> Config: 748 """ 749 Create a config 750 Creates a new config and its first version. Returns 201 on success. 751 A config is uniquely identified within an app + org scope by its 752 `virtual_path` or `lookup_key`. Creating a config at a path that already 753 exists (including archived configs) returns 409. To adopt an existing config 754 at that path and re-own it instead, pass `take_ownership: true` this 755 requires modify rights on the existing row (developer or all-powerful viewer). 756 The owner is resolved from the explicit selector params (`team`, `user`, 757 `agent`, or `system`). Developer and all-powerful viewers default to system 758 ownership when no explicit selector is provided. Exactly one owner selector 759 may be set; conflicting selectors return 422. 760 Requires app scope. 761 762 Args: 763 input: Request body. 764 input.agent: Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`. 765 input.change_description: Human-readable description of this initial version, stored on the version record. 766 input.data: Arbitrary key-value metadata stored on the version alongside the content. 767 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 768 input.kind: Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`. 769 input.lookup_key: Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners. 770 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. 771 input.org: Organization ID (`org_...`) to scope the config to a specific org. 772 input.parent: Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config. 773 input.parent_solution: Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. 774 input.raw_content: Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text. 775 input.relative_path: Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set. 776 input.system: Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`. 777 input.take_ownership: When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). 778 input.team: Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`. 779 input.user: User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`. 780 input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination. 781 782 Returns: 783 The newly created config, including its first version. 784 """ 785 return await self._http.request( 786 "/api/v1/config", 787 method="POST", 788 body=input, 789 response_type=Config, 790 ) 791 792 async def encrypt_secret(self, input: ConfigEncryptSecretInput) -> ConfigEncryptSecretResponse: 793 """ 794 Encrypt a secret for use in a config 795 Encrypts a plaintext secret and returns a ciphertext string safe for 796 embedding directly in config content using the `secret_value!` interpolation 797 syntax. The ciphertext is bound to the app's (or org's) key-encryption key 798 (KEK) so it can only be decrypted at runtime within the same scope. 799 When `org` is provided, the KEK for that org is used; otherwise the 800 viewer's own org KEK is used, falling back to the app-level KEK for viewers 801 with no org context. 802 The plaintext is never stored. Requires app scope. 803 804 Args: 805 input: Request body. 806 input.org: Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. 807 input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned. 808 809 Returns: 810 Successful response 811 """ 812 return await self._http.request( 813 "/api/v1/config/encrypt_secret", 814 method="POST", 815 body=input, 816 response_type=ConfigEncryptSecretResponse, 817 ) 818 819 async def facets( 820 self, 821 *, 822 app: str | None = None, 823 team: str | None = None, 824 user: str | None = None, 825 org: str | None = None, 826 ) -> ConfigFacets: 827 """ 828 List config facets 829 Returns the distinct config kinds and leading `virtual_path` prefixes 830 available to the viewer, each with a count of matching configs. Use this 831 to populate filter UI dropdowns without making a full list request. 832 The counts reflect every config the viewer can see in the requested scope, 833 independent of any kind, path-prefix, or lookup-key filters that might be 834 applied on a concurrent list request. This means the UI always shows every 835 option the viewer could pick, not just the values on the current filtered page. 836 Scoping follows the same rules as the list endpoint: developer and 837 all-powerful viewers see facets across all owners in the app; org-scoped 838 viewers receive their own configs' facets merged with system-owned facets; 839 all other viewers see only their resolved owner's configs. 840 841 Args: 842 app: App ID (`app_...`). Present when mounted under the developer scope; injected automatically. 843 team: Team ID (`team_...`) to scope facets to that team's configs. Mutually exclusive with `user`. 844 user: User ID (`usr_...`) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive with `team`. 845 org: Organization ID (`org_...`) to narrow facets to configs belonging to that org. 846 847 Returns: 848 Distinct config kinds and `virtual_path` prefixes with per-value counts. 849 """ 850 query: dict[str, object] = {} 851 if app is not None: 852 query["app"] = app 853 if team is not None: 854 query["team"] = team 855 if user is not None: 856 query["user"] = user 857 if org is not None: 858 query["org"] = org 859 return await self._http.request( 860 "/api/v1/config/facets", 861 query=query, 862 response_type=ConfigFacets, 863 ) 864 865 async def validate(self, input: ConfigValidateInput) -> ValidationResult: 866 """ 867 Validate config content 868 Validates raw config content against the schema for a given config kind 869 without saving anything. Returns a structured result indicating whether the 870 content is valid and, if not, a list of error messages. 871 Use this endpoint to give users early feedback before calling create or 872 update. The owner context is used for any kind-specific validation rules that 873 are owner-aware; provide the same owner you intend to use on the write call. 874 Requires app scope. 875 876 Args: 877 input: Request body. 878 input.agent: Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`. 879 input.data: Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content. 880 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 881 input.kind: Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`. 882 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation. 883 input.raw_content: Raw content bytes to validate. Parsed according to `mime_type` before schema validation. 884 input.team: Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`. 885 input.user: User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`. 886 887 Returns: 888 Validation outcome. Always HTTP 200; check the `valid` field to determine success. Includes `errors` when `valid` is `false`. 889 """ 890 return await self._http.request( 891 "/api/v1/config/validate", 892 method="POST", 893 body=input, 894 response_type=ValidationResult, 895 ) 896 897 async def delete(self, config: str) -> None: 898 """ 899 Delete a config 900 Permanently deletes a config and all its associated versions. This action is 901 irreversible. To soft-delete a config while retaining its history, use the 902 archive endpoint instead. 903 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 904 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 905 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 906 passing an owner selector when addressing by ID returns 422. 907 Returns 204 No Content on success. Requires app scope. The viewer must have 908 modify rights on the config. 909 910 Args: 911 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 912 913 Returns: 914 Empty body. HTTP 204 indicates the config and all its versions were permanently deleted. 915 """ 916 await self._http.request(f"/api/v1/config/{config}", method="DELETE") 917 918 async def get( 919 self, 920 config: str, 921 *, 922 team: str | None = None, 923 user: str | None = None, 924 agent: str | None = None, 925 system: bool | None = None, 926 org: str | None = None, 927 ) -> Config: 928 """ 929 Retrieve a config 930 Returns a single config identified by its ID, `virtual_path`, or 931 `lookup_key`. The config object includes its current version metadata but 932 not the raw content bytes; use the content endpoint to fetch the raw content. 933 When addressing by `lookup_key` or `virtual_path`, you must supply exactly 934 one owner selector (`team`, `user`, `agent`, or `system`). Passing an owner 935 selector when addressing by ID (`cfg_...`) returns 422. Both `not_found` 936 and `forbidden` outcomes are surfaced as 404 to avoid leaking config 937 existence. 938 Requires app scope. 939 940 Args: 941 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 942 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 943 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 944 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 945 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 946 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 947 948 Returns: 949 The requested config object. 950 """ 951 query: dict[str, object] = {} 952 if team is not None: 953 query["team"] = team 954 if user is not None: 955 query["user"] = user 956 if agent is not None: 957 query["agent"] = agent 958 if system is not None: 959 query["system"] = system 960 if org is not None: 961 query["org"] = org 962 return await self._http.request( 963 f"/api/v1/config/{config}", 964 query=query, 965 response_type=Config, 966 ) 967 968 async def update(self, config: str, input: ConfigUpdateInput) -> Config: 969 """ 970 Update a config 971 Updates an existing config. When `raw_content` is provided, a new version is 972 created and becomes the current version. When `raw_content` is omitted, only 973 metadata fields (`virtual_path`, `lookup_key`, `relative_path`, 974 `parent_solution`) are updated without creating a new version. 975 Use `expected_version` for optimistic concurrency control: if the config's 976 current version number does not match the supplied value the request returns 977 409. This prevents overwriting concurrent edits. 978 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 979 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 980 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 981 Both `not_found` and `forbidden` outcomes are surfaced as 404. 982 Requires app scope. The viewer must have modify rights on the config. 983 984 Args: 985 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 986 input: Request body. 987 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 988 input.change_description: Human-readable description of this update, stored on the new version record. 989 input.data: Arbitrary key-value metadata to store on the new version alongside the content. 990 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 991 input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking. 992 input.lookup_key: New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted. 993 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field. 994 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 995 input.parent_solution: Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string. 996 input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version. 997 input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`. 998 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 999 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1000 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1001 input.virtual_path: New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted. 1002 1003 Returns: 1004 The config reflecting the applied update. 1005 """ 1006 return await self._http.request( 1007 f"/api/v1/config/{config}", 1008 method="PATCH", 1009 body=input, 1010 response_type=Config, 1011 ) 1012 1013 async def archive(self, config: str, input: ConfigArchiveInput) -> Config: 1014 """ 1015 Archive a config 1016 Soft-deletes a config by marking it as archived. Archived configs are hidden 1017 from list and show endpoints but are not permanently removed; use the 1018 unarchive endpoint to restore one, or the delete endpoint for permanent 1019 removal. 1020 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1021 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1022 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1023 passing an owner selector when addressing by ID returns 422. 1024 Requires app scope. The viewer must have modify rights on the config. 1025 1026 Args: 1027 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. `virtual_path` values should be URL-encoded if they contain slashes. 1028 input: Request body. 1029 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1030 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. 1031 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1032 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1033 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1034 1035 Returns: 1036 The config in its newly archived state. 1037 """ 1038 return await self._http.request( 1039 f"/api/v1/config/{config}/archive", 1040 method="POST", 1041 body=input, 1042 response_type=Config, 1043 ) 1044 1045 async def change_owner(self, config: str, input: ConfigChangeOwnerInput) -> Config: 1046 """ 1047 Transfer ownership of a config 1048 Transfers a config to a new owner (`team`, `user`, `agent`, or `system`). 1049 Exactly one of the new-owner selectors must be provided. The config must be 1050 addressed by its ID (`cfg_...` or UUID); `virtual_path` and `lookup_key` 1051 are not accepted to avoid ambiguity look up the ID first if needed. 1052 For non-system targets the new owner's org is derived automatically from the 1053 target entity; supplying `org` in that case returns 422. For `system:true` 1054 targets, `org` controls the resulting org scope: omit to keep the existing 1055 `org_id`, supply a value to set a specific org, or pass `null`/blank to make 1056 the config app-level (operator viewers only). 1057 Operator viewers (developer credentials or all-powerful viewers) may transfer 1058 to any owner. All other viewers are restricted to owners they can themselves 1059 access (team membership, user identity, agent scope, or `system` with the 1060 appropriate privilege). 1061 Requires app scope. The viewer must have modify rights on the config. 1062 1063 Args: 1064 config: Config ID in id-form: `cfg_...` or a UUID. `lookup_key` and `virtual_path` are not accepted retrieve the config ID first if you only have a path. 1065 input: Request body. 1066 input.agent: New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`. 1067 input.org: Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422. 1068 input.system: Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`. 1069 input.team: New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`. 1070 input.user: New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`. 1071 1072 Returns: 1073 The config reflecting its new ownership. 1074 """ 1075 return await self._http.request( 1076 f"/api/v1/config/{config}/change_owner", 1077 method="POST", 1078 body=input, 1079 response_type=Config, 1080 ) 1081 1082 async def content( 1083 self, 1084 config: str, 1085 *, 1086 team: str | None = None, 1087 user: str | None = None, 1088 agent: str | None = None, 1089 system: bool | None = None, 1090 org: str | None = None, 1091 format: str | None = None, 1092 inject_protected_fields: bool | None = None, 1093 ) -> dict[str, str]: 1094 """ 1095 Retrieve a config's raw content 1096 Returns the raw byte content of a config's current version. The response 1097 `Content-Type` header reflects the config's stored MIME type unless a 1098 `format` conversion is requested. 1099 Pass `format: "yaml"` or `format: "json"` to convert between YAML and JSON 1100 on the fly. Conversion is only supported between these two formats; requesting 1101 a conversion that is not possible returns 400. 1102 By default, `virtual_path` and other platform-injected protected fields are 1103 embedded in the returned content. Set `inject_protected_fields: false` to 1104 return the stored raw bytes exactly as written. 1105 The config may be addressed by ID (`cfg_...`), `virtual_path`, or 1106 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, exactly one 1107 owner selector (`team`, `user`, `agent`, or `system`) is required. 1108 1109 Args: 1110 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1111 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1112 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1113 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1114 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1115 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1116 format: Output format for content conversion. One of `"yaml"` or `"json"`. Omit to return the content in its stored format. Returns 400 if conversion is not possible. 1117 inject_protected_fields: Whether to inject platform-managed protected fields (such as `virtual_path`) into the returned content. Defaults to `true`. Set to `false` to receive the raw stored bytes. 1118 1119 Returns: 1120 Raw config content in the stored or requested format. 1121 """ 1122 query: dict[str, object] = {} 1123 if team is not None: 1124 query["team"] = team 1125 if user is not None: 1126 query["user"] = user 1127 if agent is not None: 1128 query["agent"] = agent 1129 if system is not None: 1130 query["system"] = system 1131 if org is not None: 1132 query["org"] = org 1133 if format is not None: 1134 query["format"] = format 1135 if inject_protected_fields is not None: 1136 query["inject_protected_fields"] = inject_protected_fields 1137 return await self._http.request_raw(f"/api/v1/config/{config}/content", query=query) 1138 1139 async def unarchive(self, config: str, input: ConfigUnarchiveInput) -> Config: 1140 """ 1141 Unarchive a config 1142 Restores a previously archived config, making it visible again in list and 1143 show responses. The config's content and version history are unchanged. 1144 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1145 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1146 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1147 passing an owner selector when addressing by ID returns 422. 1148 Requires app scope. The viewer must have modify rights on the config. 1149 1150 Args: 1151 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1152 input: Request body. 1153 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1154 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1155 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1156 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1157 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1158 1159 Returns: 1160 The config in its newly restored (active) state. 1161 """ 1162 return await self._http.request( 1163 f"/api/v1/config/{config}/unarchive", 1164 method="POST", 1165 body=input, 1166 response_type=Config, 1167 ) 1168 1169 async def versions( 1170 self, 1171 config: str, 1172 *, 1173 team: str | None = None, 1174 user: str | None = None, 1175 agent: str | None = None, 1176 system: bool | None = None, 1177 org: str | None = None, 1178 ) -> ConfigVersionsResponse: 1179 """ 1180 List a config's version history 1181 Returns all versions of a config in the order they were created, most recent 1182 first. Each version includes its version number, content metadata, and change 1183 description. The raw content bytes for a specific version are not included; 1184 use the content endpoint to fetch them. 1185 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1186 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1187 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1188 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1189 Requires app scope. 1190 1191 Args: 1192 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1193 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1194 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1195 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1196 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1197 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1198 1199 Returns: 1200 Successful response 1201 """ 1202 query: dict[str, object] = {} 1203 if team is not None: 1204 query["team"] = team 1205 if user is not None: 1206 query["user"] = user 1207 if agent is not None: 1208 query["agent"] = agent 1209 if system is not None: 1210 query["system"] = system 1211 if org is not None: 1212 query["org"] = org 1213 return await self._http.request( 1214 f"/api/v1/config/{config}/versions", 1215 query=query, 1216 response_type=ConfigVersionsResponse, 1217 )
AsyncConfigResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, *, team: str | None = None, user: str | None = None, agent: str | None = None, kind: str | None = None, lookup_key: str | None = None, path_prefix: str | None = None, parents: list[str] | None = None, parent_solutions: list[str] | None = None) -> ConfigListResponse:
687 async def list( 688 self, 689 *, 690 team: str | None = None, 691 user: str | None = None, 692 agent: str | None = None, 693 kind: str | None = None, 694 lookup_key: str | None = None, 695 path_prefix: str | None = None, 696 parents: builtins.list[str] | None = None, 697 parent_solutions: builtins.list[str] | None = None, 698 ) -> ConfigListResponse: 699 """ 700 List configs 701 Returns all configs owned by the specified owner. Exactly one owner selector 702 (`team`, `user`, or `agent`) must be provided. Passing an unknown or 703 inaccessible owner returns an empty `data` array rather than an error, to 704 avoid leaking information about which teams, users, or agents exist. 705 Use the `kind`, `lookup_key`, `path_prefix`, `parents`, and 706 `parent_solutions` params to narrow results. Private config kinds are always 707 excluded from the response regardless of the viewer's permissions. 708 Results are not paginated; all matching configs are returned in a single 709 response. 710 711 Args: 712 team: Team ID (`team_...`) whose configs to list. Mutually exclusive with `user` and `agent`. 713 user: User ID (`usr_...`) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive with `team` and `agent`. 714 agent: Agent ID (`agt_...`) whose configs to list. Mutually exclusive with `team` and `user`. 715 kind: Filter results to configs of this kind, e.g. `"Agent"` or `"APITool"`. Omit to return configs of all non-private kinds. 716 lookup_key: Filter to the config with exactly this `lookup_key`. Returns at most one result. 717 path_prefix: Filter to configs whose `virtual_path` starts with this prefix, e.g. `"my-agent/"`. Useful for listing files within a folder. 718 parents: Filter to configs that are children of any of the listed parent config IDs (`cfg_...`). Pass a single ID to retrieve all children of one bundle. 719 parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (`cfg_...`). Useful for identifying all files that arrived with a given solution. 720 721 Returns: 722 Successful response 723 """ 724 query: dict[str, object] = {} 725 if team is not None: 726 query["team"] = team 727 if user is not None: 728 query["user"] = user 729 if agent is not None: 730 query["agent"] = agent 731 if kind is not None: 732 query["kind"] = kind 733 if lookup_key is not None: 734 query["lookup_key"] = lookup_key 735 if path_prefix is not None: 736 query["path_prefix"] = path_prefix 737 if parents is not None: 738 query["parents"] = parents 739 if parent_solutions is not None: 740 query["parent_solutions"] = parent_solutions 741 return await self._http.request( 742 "/api/v1/config", 743 query=query, 744 response_type=ConfigListResponse, 745 )
List configs
Returns all configs owned by the specified owner. Exactly one owner selector
(team, user, or agent) must be provided. Passing an unknown or
inaccessible owner returns an empty data array rather than an error, to
avoid leaking information about which teams, users, or agents exist.
Use the kind, lookup_key, path_prefix, parents, and
parent_solutions params to narrow results. Private config kinds are always
excluded from the response regardless of the viewer's permissions.
Results are not paginated; all matching configs are returned in a single
response.
Arguments:
- team: Team ID (
team_...) whose configs to list. Mutually exclusive withuserandagent. - user: User ID (
usr_...) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive withteamandagent. - agent: Agent ID (
agt_...) whose configs to list. Mutually exclusive withteamanduser. - kind: Filter results to configs of this kind, e.g.
"Agent"or"APITool". Omit to return configs of all non-private kinds. - lookup_key: Filter to the config with exactly this
lookup_key. Returns at most one result. - path_prefix: Filter to configs whose
virtual_pathstarts with this prefix, e.g."my-agent/". Useful for listing files within a folder. - parents: Filter to configs that are children of any of the listed parent config IDs (
cfg_...). Pass a single ID to retrieve all children of one bundle. - parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (
cfg_...). Useful for identifying all files that arrived with a given solution.
Returns:
Successful response
747 async def create(self, input: ConfigCreateInput) -> Config: 748 """ 749 Create a config 750 Creates a new config and its first version. Returns 201 on success. 751 A config is uniquely identified within an app + org scope by its 752 `virtual_path` or `lookup_key`. Creating a config at a path that already 753 exists (including archived configs) returns 409. To adopt an existing config 754 at that path and re-own it instead, pass `take_ownership: true` this 755 requires modify rights on the existing row (developer or all-powerful viewer). 756 The owner is resolved from the explicit selector params (`team`, `user`, 757 `agent`, or `system`). Developer and all-powerful viewers default to system 758 ownership when no explicit selector is provided. Exactly one owner selector 759 may be set; conflicting selectors return 422. 760 Requires app scope. 761 762 Args: 763 input: Request body. 764 input.agent: Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`. 765 input.change_description: Human-readable description of this initial version, stored on the version record. 766 input.data: Arbitrary key-value metadata stored on the version alongside the content. 767 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 768 input.kind: Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`. 769 input.lookup_key: Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners. 770 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. 771 input.org: Organization ID (`org_...`) to scope the config to a specific org. 772 input.parent: Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config. 773 input.parent_solution: Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. 774 input.raw_content: Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text. 775 input.relative_path: Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set. 776 input.system: Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`. 777 input.take_ownership: When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). 778 input.team: Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`. 779 input.user: User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`. 780 input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination. 781 782 Returns: 783 The newly created config, including its first version. 784 """ 785 return await self._http.request( 786 "/api/v1/config", 787 method="POST", 788 body=input, 789 response_type=Config, 790 )
Create a config
Creates a new config and its first version. Returns 201 on success.
A config is uniquely identified within an app + org scope by its
virtual_path or lookup_key. Creating a config at a path that already
exists (including archived configs) returns 409. To adopt an existing config
at that path and re-own it instead, pass take_ownership: true this
requires modify rights on the existing row (developer or all-powerful viewer).
The owner is resolved from the explicit selector params (team, user,
agent, or system). Developer and all-powerful viewers default to system
ownership when no explicit selector is provided. Exactly one owner selector
may be set; conflicting selectors return 422.
Requires app scope.
Arguments:
- input: Request body.
- input.agent: Agent ID (
agt_...) to assign as the config owner. Mutually exclusive withteam,user, andsystem. - input.change_description: Human-readable description of this initial version, stored on the version record.
- input.data: Arbitrary key-value metadata stored on the version alongside the content.
- input.data_encoding: Encoding of
raw_content. Omit or set"raw"for literal content; set"base64"when sending binary content such as images or PDFs in JSON. - input.kind: Config kind that determines the schema and behavior of the config, e.g.
"Agent"or"APITool". - input.lookup_key: Optional stable key for looking up this config independent of its
virtual_path. Must be unique within the app + org scope across all owners. - input.mime_type: MIME type of
raw_content, e.g."application/x-yaml"or"application/json". - input.org: Organization ID (
org_...) to scope the config to a specific org. - input.parent: Parent config ID (
cfg_...) for bundle children, e.g. files belonging to a Skill. Required together withrelative_pathwhen creating a child config. - input.parent_solution: Solution config ID (
cfg_...) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. - input.raw_content: Raw content bytes for the first version. Accepted formats depend on
mime_type; typical values are YAML or JSON text. - input.relative_path: Path of this config within its parent bundle, e.g.
"prompts/system.md". Required whenparentis set. - input.system: Set
trueto create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive withteam,user, andagent. - input.take_ownership: When
trueand a config already exists at the specifiedvirtual_pathorlookup_keyunder a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). - input.team: Team ID (
team_...) to assign as the config owner. Mutually exclusive withuser,agent, andsystem. - input.user: User ID (
usr_...) to assign as the config owner. Mutually exclusive withteam,agent, andsystem. - input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g.
"my-agent/v1". Must be unique within the app + org + owner combination.
Returns:
The newly created config, including its first version.
792 async def encrypt_secret(self, input: ConfigEncryptSecretInput) -> ConfigEncryptSecretResponse: 793 """ 794 Encrypt a secret for use in a config 795 Encrypts a plaintext secret and returns a ciphertext string safe for 796 embedding directly in config content using the `secret_value!` interpolation 797 syntax. The ciphertext is bound to the app's (or org's) key-encryption key 798 (KEK) so it can only be decrypted at runtime within the same scope. 799 When `org` is provided, the KEK for that org is used; otherwise the 800 viewer's own org KEK is used, falling back to the app-level KEK for viewers 801 with no org context. 802 The plaintext is never stored. Requires app scope. 803 804 Args: 805 input: Request body. 806 input.org: Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. 807 input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned. 808 809 Returns: 810 Successful response 811 """ 812 return await self._http.request( 813 "/api/v1/config/encrypt_secret", 814 method="POST", 815 body=input, 816 response_type=ConfigEncryptSecretResponse, 817 )
Encrypt a secret for use in a config
Encrypts a plaintext secret and returns a ciphertext string safe for
embedding directly in config content using the secret_value! interpolation
syntax. The ciphertext is bound to the app's (or org's) key-encryption key
(KEK) so it can only be decrypted at runtime within the same scope.
When org is provided, the KEK for that org is used; otherwise the
viewer's own org KEK is used, falling back to the app-level KEK for viewers
with no org context.
The plaintext is never stored. Requires app scope.
Arguments:
- input: Request body.
- input.org: Organization ID (
org_...) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. - input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned.
Returns:
Successful response
async def
facets( self, *, app: str | None = None, team: str | None = None, user: str | None = None, org: str | None = None) -> archastro.platform.types.config.ConfigFacets:
819 async def facets( 820 self, 821 *, 822 app: str | None = None, 823 team: str | None = None, 824 user: str | None = None, 825 org: str | None = None, 826 ) -> ConfigFacets: 827 """ 828 List config facets 829 Returns the distinct config kinds and leading `virtual_path` prefixes 830 available to the viewer, each with a count of matching configs. Use this 831 to populate filter UI dropdowns without making a full list request. 832 The counts reflect every config the viewer can see in the requested scope, 833 independent of any kind, path-prefix, or lookup-key filters that might be 834 applied on a concurrent list request. This means the UI always shows every 835 option the viewer could pick, not just the values on the current filtered page. 836 Scoping follows the same rules as the list endpoint: developer and 837 all-powerful viewers see facets across all owners in the app; org-scoped 838 viewers receive their own configs' facets merged with system-owned facets; 839 all other viewers see only their resolved owner's configs. 840 841 Args: 842 app: App ID (`app_...`). Present when mounted under the developer scope; injected automatically. 843 team: Team ID (`team_...`) to scope facets to that team's configs. Mutually exclusive with `user`. 844 user: User ID (`usr_...`) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive with `team`. 845 org: Organization ID (`org_...`) to narrow facets to configs belonging to that org. 846 847 Returns: 848 Distinct config kinds and `virtual_path` prefixes with per-value counts. 849 """ 850 query: dict[str, object] = {} 851 if app is not None: 852 query["app"] = app 853 if team is not None: 854 query["team"] = team 855 if user is not None: 856 query["user"] = user 857 if org is not None: 858 query["org"] = org 859 return await self._http.request( 860 "/api/v1/config/facets", 861 query=query, 862 response_type=ConfigFacets, 863 )
List config facets
Returns the distinct config kinds and leading virtual_path prefixes
available to the viewer, each with a count of matching configs. Use this
to populate filter UI dropdowns without making a full list request.
The counts reflect every config the viewer can see in the requested scope,
independent of any kind, path-prefix, or lookup-key filters that might be
applied on a concurrent list request. This means the UI always shows every
option the viewer could pick, not just the values on the current filtered page.
Scoping follows the same rules as the list endpoint: developer and
all-powerful viewers see facets across all owners in the app; org-scoped
viewers receive their own configs' facets merged with system-owned facets;
all other viewers see only their resolved owner's configs.
Arguments:
- app: App ID (
app_...). Present when mounted under the developer scope; injected automatically. - team: Team ID (
team_...) to scope facets to that team's configs. Mutually exclusive withuser. - user: User ID (
usr_...) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive withteam. - org: Organization ID (
org_...) to narrow facets to configs belonging to that org.
Returns:
Distinct config kinds and
virtual_pathprefixes with per-value counts.
async def
validate( self, input: ConfigValidateInput) -> archastro.platform.types.common.ValidationResult:
865 async def validate(self, input: ConfigValidateInput) -> ValidationResult: 866 """ 867 Validate config content 868 Validates raw config content against the schema for a given config kind 869 without saving anything. Returns a structured result indicating whether the 870 content is valid and, if not, a list of error messages. 871 Use this endpoint to give users early feedback before calling create or 872 update. The owner context is used for any kind-specific validation rules that 873 are owner-aware; provide the same owner you intend to use on the write call. 874 Requires app scope. 875 876 Args: 877 input: Request body. 878 input.agent: Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`. 879 input.data: Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content. 880 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 881 input.kind: Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`. 882 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation. 883 input.raw_content: Raw content bytes to validate. Parsed according to `mime_type` before schema validation. 884 input.team: Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`. 885 input.user: User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`. 886 887 Returns: 888 Validation outcome. Always HTTP 200; check the `valid` field to determine success. Includes `errors` when `valid` is `false`. 889 """ 890 return await self._http.request( 891 "/api/v1/config/validate", 892 method="POST", 893 body=input, 894 response_type=ValidationResult, 895 )
Validate config content Validates raw config content against the schema for a given config kind without saving anything. Returns a structured result indicating whether the content is valid and, if not, a list of error messages. Use this endpoint to give users early feedback before calling create or update. The owner context is used for any kind-specific validation rules that are owner-aware; provide the same owner you intend to use on the write call. Requires app scope.
Arguments:
- input: Request body.
- input.agent: Agent ID (
agt_...) that would own the config. Used for owner-aware validation rules. Mutually exclusive withteamanduser. - input.data: Optional metadata used by kind-specific validation. File and Image configs require
data.namewhen validating direct binary content. - input.data_encoding: Encoding of
raw_content. Omit or set"raw"for literal content; set"base64"when sending binary content such as images or PDFs in JSON. - input.kind: Config kind whose schema the content is validated against, e.g.
"Agent"or"APITool". - input.mime_type: MIME type of
raw_content, e.g."application/x-yaml"or"application/json". Used to parse the content before validation. - input.raw_content: Raw content bytes to validate. Parsed according to
mime_typebefore schema validation. - input.team: Team ID (
team_...) that would own the config. Used for owner-aware validation rules. Mutually exclusive withuserandagent. - input.user: User ID (
usr_...) that would own the config. Used for owner-aware validation rules. Mutually exclusive withteamandagent.
Returns:
Validation outcome. Always HTTP 200; check the
validfield to determine success. Includeserrorswhenvalidisfalse.
async def
delete(self, config: str) -> None:
897 async def delete(self, config: str) -> None: 898 """ 899 Delete a config 900 Permanently deletes a config and all its associated versions. This action is 901 irreversible. To soft-delete a config while retaining its history, use the 902 archive endpoint instead. 903 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 904 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 905 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 906 passing an owner selector when addressing by ID returns 422. 907 Returns 204 No Content on success. Requires app scope. The viewer must have 908 modify rights on the config. 909 910 Args: 911 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 912 913 Returns: 914 Empty body. HTTP 204 indicates the config and all its versions were permanently deleted. 915 """ 916 await self._http.request(f"/api/v1/config/{config}", method="DELETE")
Delete a config
Permanently deletes a config and all its associated versions. This action is
irreversible. To soft-delete a config while retaining its history, use the
archive endpoint instead.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system);
passing an owner selector when addressing by ID returns 422.
Returns 204 No Content on success. Requires app scope. The viewer must have
modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes.
Returns:
Empty body. HTTP 204 indicates the config and all its versions were permanently deleted.
async def
get( self, config: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, system: bool | None = None, org: str | None = None) -> archastro.platform.types.config.Config:
918 async def get( 919 self, 920 config: str, 921 *, 922 team: str | None = None, 923 user: str | None = None, 924 agent: str | None = None, 925 system: bool | None = None, 926 org: str | None = None, 927 ) -> Config: 928 """ 929 Retrieve a config 930 Returns a single config identified by its ID, `virtual_path`, or 931 `lookup_key`. The config object includes its current version metadata but 932 not the raw content bytes; use the content endpoint to fetch the raw content. 933 When addressing by `lookup_key` or `virtual_path`, you must supply exactly 934 one owner selector (`team`, `user`, `agent`, or `system`). Passing an owner 935 selector when addressing by ID (`cfg_...`) returns 422. Both `not_found` 936 and `forbidden` outcomes are surfaced as 404 to avoid leaking config 937 existence. 938 Requires app scope. 939 940 Args: 941 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 942 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 943 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 944 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 945 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 946 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 947 948 Returns: 949 The requested config object. 950 """ 951 query: dict[str, object] = {} 952 if team is not None: 953 query["team"] = team 954 if user is not None: 955 query["user"] = user 956 if agent is not None: 957 query["agent"] = agent 958 if system is not None: 959 query["system"] = system 960 if org is not None: 961 query["org"] = org 962 return await self._http.request( 963 f"/api/v1/config/{config}", 964 query=query, 965 response_type=Config, 966 )
Retrieve a config
Returns a single config identified by its ID, virtual_path, or
lookup_key. The config object includes its current version metadata but
not the raw content bytes; use the content endpoint to fetch the raw content.
When addressing by lookup_key or virtual_path, you must supply exactly
one owner selector (team, user, agent, or system). Passing an owner
selector when addressing by ID (cfg_...) returns 422. Both not_found
and forbidden outcomes are surfaced as 404 to avoid leaking config
existence.
Requires app scope.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org.
Returns:
The requested config object.
async def
update( self, config: str, input: ConfigUpdateInput) -> archastro.platform.types.config.Config:
968 async def update(self, config: str, input: ConfigUpdateInput) -> Config: 969 """ 970 Update a config 971 Updates an existing config. When `raw_content` is provided, a new version is 972 created and becomes the current version. When `raw_content` is omitted, only 973 metadata fields (`virtual_path`, `lookup_key`, `relative_path`, 974 `parent_solution`) are updated without creating a new version. 975 Use `expected_version` for optimistic concurrency control: if the config's 976 current version number does not match the supplied value the request returns 977 409. This prevents overwriting concurrent edits. 978 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 979 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 980 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 981 Both `not_found` and `forbidden` outcomes are surfaced as 404. 982 Requires app scope. The viewer must have modify rights on the config. 983 984 Args: 985 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 986 input: Request body. 987 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 988 input.change_description: Human-readable description of this update, stored on the new version record. 989 input.data: Arbitrary key-value metadata to store on the new version alongside the content. 990 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 991 input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking. 992 input.lookup_key: New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted. 993 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field. 994 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 995 input.parent_solution: Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string. 996 input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version. 997 input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`. 998 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 999 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1000 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1001 input.virtual_path: New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted. 1002 1003 Returns: 1004 The config reflecting the applied update. 1005 """ 1006 return await self._http.request( 1007 f"/api/v1/config/{config}", 1008 method="PATCH", 1009 body=input, 1010 response_type=Config, 1011 )
Update a config
Updates an existing config. When raw_content is provided, a new version is
created and becomes the current version. When raw_content is omitted, only
metadata fields (virtual_path, lookup_key, relative_path,
parent_solution) are updated without creating a new version.
Use expected_version for optimistic concurrency control: if the config's
current version number does not match the supplied value the request returns
- This prevents overwriting concurrent edits.
The config may be addressed by its ID (
cfg_...),virtual_path, orlookup_key. When addressing bylookup_keyorvirtual_path, you must supply exactly one owner selector (team,user,agent, orsystem). Bothnot_foundandforbiddenoutcomes are surfaced as 404. Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - input: Request body.
- input.agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.change_description: Human-readable description of this update, stored on the new version record.
- input.data: Arbitrary key-value metadata to store on the new version alongside the content.
- input.data_encoding: Encoding of
raw_content. Omit or set"raw"for literal content; set"base64"when sending binary content such as images or PDFs in JSON. - input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking.
- input.lookup_key: New
lookup_keyfor the config. Updates the key without creating a new version whenraw_contentis omitted. - input.mime_type: MIME type of
raw_content, e.g."application/x-yaml"or"application/json". Defaults to the existing MIME type whenraw_contentis provided without this field. - input.org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. - input.parent_solution: Solution config ID (
cfg_...) to set as the config's parent solution provenance. Clears the value when set to an empty string. - input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version.
- input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a
parent. - input.system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - input.team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.virtual_path: New
virtual_pathfor the config. Updates the path without creating a new version whenraw_contentis omitted.
Returns:
The config reflecting the applied update.
async def
archive( self, config: str, input: ConfigArchiveInput) -> archastro.platform.types.config.Config:
1013 async def archive(self, config: str, input: ConfigArchiveInput) -> Config: 1014 """ 1015 Archive a config 1016 Soft-deletes a config by marking it as archived. Archived configs are hidden 1017 from list and show endpoints but are not permanently removed; use the 1018 unarchive endpoint to restore one, or the delete endpoint for permanent 1019 removal. 1020 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1021 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1022 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1023 passing an owner selector when addressing by ID returns 422. 1024 Requires app scope. The viewer must have modify rights on the config. 1025 1026 Args: 1027 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. `virtual_path` values should be URL-encoded if they contain slashes. 1028 input: Request body. 1029 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1030 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. 1031 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1032 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1033 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1034 1035 Returns: 1036 The config in its newly archived state. 1037 """ 1038 return await self._http.request( 1039 f"/api/v1/config/{config}/archive", 1040 method="POST", 1041 body=input, 1042 response_type=Config, 1043 )
Archive a config
Soft-deletes a config by marking it as archived. Archived configs are hidden
from list and show endpoints but are not permanently removed; use the
unarchive endpoint to restore one, or the delete endpoint for permanent
removal.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system);
passing an owner selector when addressing by ID returns 422.
Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key.virtual_pathvalues should be URL-encoded if they contain slashes. - input: Request body.
- input.agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. - input.system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - input.team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key.
Returns:
The config in its newly archived state.
async def
change_owner( self, config: str, input: ConfigChangeOwnerInput) -> archastro.platform.types.config.Config:
1045 async def change_owner(self, config: str, input: ConfigChangeOwnerInput) -> Config: 1046 """ 1047 Transfer ownership of a config 1048 Transfers a config to a new owner (`team`, `user`, `agent`, or `system`). 1049 Exactly one of the new-owner selectors must be provided. The config must be 1050 addressed by its ID (`cfg_...` or UUID); `virtual_path` and `lookup_key` 1051 are not accepted to avoid ambiguity look up the ID first if needed. 1052 For non-system targets the new owner's org is derived automatically from the 1053 target entity; supplying `org` in that case returns 422. For `system:true` 1054 targets, `org` controls the resulting org scope: omit to keep the existing 1055 `org_id`, supply a value to set a specific org, or pass `null`/blank to make 1056 the config app-level (operator viewers only). 1057 Operator viewers (developer credentials or all-powerful viewers) may transfer 1058 to any owner. All other viewers are restricted to owners they can themselves 1059 access (team membership, user identity, agent scope, or `system` with the 1060 appropriate privilege). 1061 Requires app scope. The viewer must have modify rights on the config. 1062 1063 Args: 1064 config: Config ID in id-form: `cfg_...` or a UUID. `lookup_key` and `virtual_path` are not accepted retrieve the config ID first if you only have a path. 1065 input: Request body. 1066 input.agent: New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`. 1067 input.org: Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422. 1068 input.system: Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`. 1069 input.team: New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`. 1070 input.user: New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`. 1071 1072 Returns: 1073 The config reflecting its new ownership. 1074 """ 1075 return await self._http.request( 1076 f"/api/v1/config/{config}/change_owner", 1077 method="POST", 1078 body=input, 1079 response_type=Config, 1080 )
Transfer ownership of a config
Transfers a config to a new owner (team, user, agent, or system).
Exactly one of the new-owner selectors must be provided. The config must be
addressed by its ID (cfg_... or UUID); virtual_path and lookup_key
are not accepted to avoid ambiguity look up the ID first if needed.
For non-system targets the new owner's org is derived automatically from the
target entity; supplying org in that case returns 422. For system:true
targets, org controls the resulting org scope: omit to keep the existing
org_id, supply a value to set a specific org, or pass null/blank to make
the config app-level (operator viewers only).
Operator viewers (developer credentials or all-powerful viewers) may transfer
to any owner. All other viewers are restricted to owners they can themselves
access (team membership, user identity, agent scope, or system with the
appropriate privilege).
Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config ID in id-form:
cfg_...or a UUID.lookup_keyandvirtual_pathare not accepted retrieve the config ID first if you only have a path. - input: Request body.
- input.agent: New owner: Agent ID (
agt_...). Mutually exclusive withteam,user, andsystem. - input.org: Only valid when
system:true. Omit to keep the config's existingorg_id; supply an org ID (org_...) to set a specific org scope; pass blank ornullto make the config app-level (operator viewers only). Settingorgforteam,user, oragenttargets returns 422. - input.system: Set
trueto transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive withteam,user, andagent. - input.team: New owner: Team ID (
team_...). Mutually exclusive withuser,agent, andsystem. - input.user: New owner: User ID (
usr_...). Mutually exclusive withteam,agent, andsystem.
Returns:
The config reflecting its new ownership.
async def
content( self, config: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, system: bool | None = None, org: str | None = None, format: str | None = None, inject_protected_fields: bool | None = None) -> dict[str, str]:
1082 async def content( 1083 self, 1084 config: str, 1085 *, 1086 team: str | None = None, 1087 user: str | None = None, 1088 agent: str | None = None, 1089 system: bool | None = None, 1090 org: str | None = None, 1091 format: str | None = None, 1092 inject_protected_fields: bool | None = None, 1093 ) -> dict[str, str]: 1094 """ 1095 Retrieve a config's raw content 1096 Returns the raw byte content of a config's current version. The response 1097 `Content-Type` header reflects the config's stored MIME type unless a 1098 `format` conversion is requested. 1099 Pass `format: "yaml"` or `format: "json"` to convert between YAML and JSON 1100 on the fly. Conversion is only supported between these two formats; requesting 1101 a conversion that is not possible returns 400. 1102 By default, `virtual_path` and other platform-injected protected fields are 1103 embedded in the returned content. Set `inject_protected_fields: false` to 1104 return the stored raw bytes exactly as written. 1105 The config may be addressed by ID (`cfg_...`), `virtual_path`, or 1106 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, exactly one 1107 owner selector (`team`, `user`, `agent`, or `system`) is required. 1108 1109 Args: 1110 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1111 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1112 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1113 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1114 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1115 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1116 format: Output format for content conversion. One of `"yaml"` or `"json"`. Omit to return the content in its stored format. Returns 400 if conversion is not possible. 1117 inject_protected_fields: Whether to inject platform-managed protected fields (such as `virtual_path`) into the returned content. Defaults to `true`. Set to `false` to receive the raw stored bytes. 1118 1119 Returns: 1120 Raw config content in the stored or requested format. 1121 """ 1122 query: dict[str, object] = {} 1123 if team is not None: 1124 query["team"] = team 1125 if user is not None: 1126 query["user"] = user 1127 if agent is not None: 1128 query["agent"] = agent 1129 if system is not None: 1130 query["system"] = system 1131 if org is not None: 1132 query["org"] = org 1133 if format is not None: 1134 query["format"] = format 1135 if inject_protected_fields is not None: 1136 query["inject_protected_fields"] = inject_protected_fields 1137 return await self._http.request_raw(f"/api/v1/config/{config}/content", query=query)
Retrieve a config's raw content
Returns the raw byte content of a config's current version. The response
Content-Type header reflects the config's stored MIME type unless a
format conversion is requested.
Pass format: "yaml" or format: "json" to convert between YAML and JSON
on the fly. Conversion is only supported between these two formats; requesting
a conversion that is not possible returns 400.
By default, virtual_path and other platform-injected protected fields are
embedded in the returned content. Set inject_protected_fields: false to
return the stored raw bytes exactly as written.
The config may be addressed by ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, exactly one
owner selector (team, user, agent, or system) is required.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. - format: Output format for content conversion. One of
"yaml"or"json". Omit to return the content in its stored format. Returns 400 if conversion is not possible. - inject_protected_fields: Whether to inject platform-managed protected fields (such as
virtual_path) into the returned content. Defaults totrue. Set tofalseto receive the raw stored bytes.
Returns:
Raw config content in the stored or requested format.
async def
unarchive( self, config: str, input: ConfigUnarchiveInput) -> archastro.platform.types.config.Config:
1139 async def unarchive(self, config: str, input: ConfigUnarchiveInput) -> Config: 1140 """ 1141 Unarchive a config 1142 Restores a previously archived config, making it visible again in list and 1143 show responses. The config's content and version history are unchanged. 1144 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1145 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1146 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1147 passing an owner selector when addressing by ID returns 422. 1148 Requires app scope. The viewer must have modify rights on the config. 1149 1150 Args: 1151 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1152 input: Request body. 1153 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1154 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1155 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1156 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1157 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1158 1159 Returns: 1160 The config in its newly restored (active) state. 1161 """ 1162 return await self._http.request( 1163 f"/api/v1/config/{config}/unarchive", 1164 method="POST", 1165 body=input, 1166 response_type=Config, 1167 )
Unarchive a config
Restores a previously archived config, making it visible again in list and
show responses. The config's content and version history are unchanged.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system);
passing an owner selector when addressing by ID returns 422.
Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - input: Request body.
- input.agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. - input.system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - input.team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key.
Returns:
The config in its newly restored (active) state.
async def
versions( self, config: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, system: bool | None = None, org: str | None = None) -> ConfigVersionsResponse:
1169 async def versions( 1170 self, 1171 config: str, 1172 *, 1173 team: str | None = None, 1174 user: str | None = None, 1175 agent: str | None = None, 1176 system: bool | None = None, 1177 org: str | None = None, 1178 ) -> ConfigVersionsResponse: 1179 """ 1180 List a config's version history 1181 Returns all versions of a config in the order they were created, most recent 1182 first. Each version includes its version number, content metadata, and change 1183 description. The raw content bytes for a specific version are not included; 1184 use the content endpoint to fetch them. 1185 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1186 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1187 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1188 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1189 Requires app scope. 1190 1191 Args: 1192 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1193 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1194 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1195 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1196 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1197 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1198 1199 Returns: 1200 Successful response 1201 """ 1202 query: dict[str, object] = {} 1203 if team is not None: 1204 query["team"] = team 1205 if user is not None: 1206 query["user"] = user 1207 if agent is not None: 1208 query["agent"] = agent 1209 if system is not None: 1210 query["system"] = system 1211 if org is not None: 1212 query["org"] = org 1213 return await self._http.request( 1214 f"/api/v1/config/{config}/versions", 1215 query=query, 1216 response_type=ConfigVersionsResponse, 1217 )
List a config's version history
Returns all versions of a config in the order they were created, most recent
first. Each version includes its version number, content metadata, and change
description. The raw content bytes for a specific version are not included;
use the content endpoint to fetch them.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system).
Both not_found and forbidden outcomes are surfaced as 404.
Requires app scope.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org.
Returns:
Successful response
class
KindResource:
1220class KindResource: 1221 def __init__(self, http: SyncHttpClient): 1222 self._http = http 1223 1224 def list(self, *, kind: builtins.list[str] | None = None) -> KindListResponse: 1225 """ 1226 List config kinds 1227 Returns all config kinds registered in the platform, sorted alphabetically by name. 1228 Each entry describes a type of configuration object (e.g., `"Agent"`, `"APITool"`) and 1229 indicates whether a JSON schema and a YAML sample are available for it. 1230 Any authenticated user may call this endpoint; no ownership scope is required. 1231 Pass one or more `kind` values to restrict the response to those specific kinds. 1232 Omit the parameter to receive the full list of non-private kinds. 1233 1234 Args: 1235 kind: One or more config kind names to include in the response (e.g., `"Agent"`, `"APITool"`). Omit to return all non-private kinds. 1236 1237 Returns: 1238 Successful response 1239 """ 1240 query: dict[str, object] = {} 1241 if kind is not None: 1242 query["kind"] = kind 1243 return self._http.request( 1244 "/api/v1/config/kinds", 1245 query=query, 1246 response_type=KindListResponse, 1247 ) 1248 1249 def schema(self, kind: str) -> ConfigKindSchema: 1250 """ 1251 Retrieve a config kind schema 1252 Returns the JSON schema and a YAML sample for a single config kind. Use this to 1253 understand the structure a config object of that kind must follow before creating 1254 or validating one. 1255 The `json_schema` field is `null` when the kind has no machine-readable schema 1256 defined. The `sample_yaml` field is `null` when no sample is available. Any 1257 authenticated user may call this endpoint; no ownership scope is required. 1258 Returns 404 if the kind name does not match a registered, non-private config kind. 1259 1260 Args: 1261 kind: Name of the config kind to retrieve (e.g., `"Agent"`, `"APITool"`). Must match a registered, non-private kind exactly. 1262 1263 Returns: 1264 The JSON schema and YAML sample for the requested config kind. 1265 """ 1266 return self._http.request( 1267 f"/api/v1/config/kinds/{kind}/schema", 1268 response_type=ConfigKindSchema, 1269 )
KindResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1224 def list(self, *, kind: builtins.list[str] | None = None) -> KindListResponse: 1225 """ 1226 List config kinds 1227 Returns all config kinds registered in the platform, sorted alphabetically by name. 1228 Each entry describes a type of configuration object (e.g., `"Agent"`, `"APITool"`) and 1229 indicates whether a JSON schema and a YAML sample are available for it. 1230 Any authenticated user may call this endpoint; no ownership scope is required. 1231 Pass one or more `kind` values to restrict the response to those specific kinds. 1232 Omit the parameter to receive the full list of non-private kinds. 1233 1234 Args: 1235 kind: One or more config kind names to include in the response (e.g., `"Agent"`, `"APITool"`). Omit to return all non-private kinds. 1236 1237 Returns: 1238 Successful response 1239 """ 1240 query: dict[str, object] = {} 1241 if kind is not None: 1242 query["kind"] = kind 1243 return self._http.request( 1244 "/api/v1/config/kinds", 1245 query=query, 1246 response_type=KindListResponse, 1247 )
List config kinds
Returns all config kinds registered in the platform, sorted alphabetically by name.
Each entry describes a type of configuration object (e.g., "Agent", "APITool") and
indicates whether a JSON schema and a YAML sample are available for it.
Any authenticated user may call this endpoint; no ownership scope is required.
Pass one or more kind values to restrict the response to those specific kinds.
Omit the parameter to receive the full list of non-private kinds.
Arguments:
- kind: One or more config kind names to include in the response (e.g.,
"Agent","APITool"). Omit to return all non-private kinds.
Returns:
Successful response
1249 def schema(self, kind: str) -> ConfigKindSchema: 1250 """ 1251 Retrieve a config kind schema 1252 Returns the JSON schema and a YAML sample for a single config kind. Use this to 1253 understand the structure a config object of that kind must follow before creating 1254 or validating one. 1255 The `json_schema` field is `null` when the kind has no machine-readable schema 1256 defined. The `sample_yaml` field is `null` when no sample is available. Any 1257 authenticated user may call this endpoint; no ownership scope is required. 1258 Returns 404 if the kind name does not match a registered, non-private config kind. 1259 1260 Args: 1261 kind: Name of the config kind to retrieve (e.g., `"Agent"`, `"APITool"`). Must match a registered, non-private kind exactly. 1262 1263 Returns: 1264 The JSON schema and YAML sample for the requested config kind. 1265 """ 1266 return self._http.request( 1267 f"/api/v1/config/kinds/{kind}/schema", 1268 response_type=ConfigKindSchema, 1269 )
Retrieve a config kind schema
Returns the JSON schema and a YAML sample for a single config kind. Use this to
understand the structure a config object of that kind must follow before creating
or validating one.
The json_schema field is null when the kind has no machine-readable schema
defined. The sample_yaml field is null when no sample is available. Any
authenticated user may call this endpoint; no ownership scope is required.
Returns 404 if the kind name does not match a registered, non-private config kind.
Arguments:
- kind: Name of the config kind to retrieve (e.g.,
"Agent","APITool"). Must match a registered, non-private kind exactly.
Returns:
The JSON schema and YAML sample for the requested config kind.
class
SystemResource:
1272class SystemResource: 1273 def __init__(self, http: SyncHttpClient): 1274 self._http = http 1275 1276 def list( 1277 self, 1278 *, 1279 kind: str | None = None, 1280 kinds: builtins.list[str] | None = None, 1281 excluded_path_prefixes: builtins.list[str] | None = None, 1282 page: int | None = None, 1283 page_size: int | None = None, 1284 ) -> SystemListResponse: 1285 """ 1286 List system configs 1287 Returns a paginated list of system (template) configs from the filesystem-backed 1288 manifest. Results are always ordered by `virtual_path` ascending. 1289 Filter by one or more config kinds using `kind` (single value) or `kinds` (array). 1290 Both filters may be supplied together for backward compatibility; `kinds` takes 1291 precedence when both are present. Exclude specific path namespaces with 1292 `excluded_path_prefixes`. 1293 Use `page` and `page_size` to paginate. Page size is clamped to a maximum of 200; 1294 requests exceeding this limit are silently clamped rather than rejected. 1295 1296 Args: 1297 kind: Filter results to a single config kind, e.g. `"Agent"` or `"APITool"`. Use `kinds` to filter by multiple kinds at once. 1298 kinds: Filter results to configs whose `kind` is in this list. When both `kind` and `kinds` are provided, `kinds` takes precedence. 1299 excluded_path_prefixes: Exclude configs whose `virtual_path` starts with any of the listed string prefixes. 1300 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1301 page_size: Number of results per page. Defaults to `50`; maximum is `200`. Values above the maximum are clamped to `200`. 1302 1303 Returns: 1304 Successful response 1305 """ 1306 query: dict[str, object] = {} 1307 if kind is not None: 1308 query["kind"] = kind 1309 if kinds is not None: 1310 query["kinds"] = kinds 1311 if excluded_path_prefixes is not None: 1312 query["excluded_path_prefixes"] = excluded_path_prefixes 1313 if page is not None: 1314 query["page"] = page 1315 if page_size is not None: 1316 query["page_size"] = page_size 1317 return self._http.request( 1318 "/api/v1/config/system", 1319 query=query, 1320 response_type=SystemListResponse, 1321 ) 1322 1323 def facets(self) -> ConfigFacets: 1324 """ 1325 Retrieve system config facets 1326 Returns the distinct `kind` values and leading `virtual_path` prefixes present 1327 in the system (template) config manifest, each accompanied by a count of matching 1328 configs. Use this data to populate filter UIs or to determine which config kinds 1329 are available before listing or cloning. 1330 The response reflects the filesystem-backed template manifest and does not include 1331 user- or team-owned configs. 1332 1333 Returns: 1334 Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs. 1335 """ 1336 return self._http.request("/api/v1/config/system/facets", response_type=ConfigFacets) 1337 1338 def get(self, system: str) -> Config: 1339 """ 1340 Retrieve a system config 1341 Returns a single system (template) config identified by its `virtual_path` or 1342 `lookup_key`. The `system` parameter value is URL-decoded before lookup, so 1343 path segments with special characters may be passed URL-encoded. 1344 System configs are filesystem-backed templates and are readable by any 1345 authenticated caller regardless of team or user ownership. Returns 404 when no 1346 system config matches the given identifier. 1347 1348 Args: 1349 system: Identifier of the system config to retrieve either its `virtual_path` or its `lookup_key`. May be URL-encoded. 1350 1351 Returns: 1352 The requested system config, including its current version and all metadata fields. 1353 """ 1354 return self._http.request(f"/api/v1/config/system/{system}", response_type=Config) 1355 1356 def clone(self, system: str, input: SystemCloneInput) -> Config: 1357 """ 1358 Clone a system config 1359 Creates a copy of a system (template) config and transfers ownership to a team 1360 or user. All dependencies bundled with the source config are cloned alongside it. 1361 Responds with HTTP 201 and the newly created config on success. 1362 You must specify exactly one destination owner via `team` or `user`. Callers 1363 authenticated as an app (developer portal) may omit the owner the clone is 1364 then scoped to the system owner automatically. 1365 Use `virtual_path` and `lookup_key` to override the corresponding fields on the 1366 clone; omitting them carries the values from the source. 1367 1368 Args: 1369 system: Identifier of the source system config either its `virtual_path` or its `lookup_key`. 1370 input: Request body. 1371 input.lookup_key: Override the `lookup_key` on the cloned config. When omitted, the source value is used. 1372 input.org: Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org. 1373 input.team: Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped. 1374 input.user: User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped. 1375 input.virtual_path: Override the `virtual_path` on the cloned config. When omitted, the source value is used. 1376 1377 Returns: 1378 The newly created config, including all cloned fields and its assigned ID. 1379 """ 1380 return self._http.request( 1381 f"/api/v1/config/system/{system}/clone", 1382 method="POST", 1383 body=input, 1384 response_type=Config, 1385 )
SystemResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, *, kind: str | None = None, kinds: list[str] | None = None, excluded_path_prefixes: list[str] | None = None, page: int | None = None, page_size: int | None = None) -> SystemListResponse:
1276 def list( 1277 self, 1278 *, 1279 kind: str | None = None, 1280 kinds: builtins.list[str] | None = None, 1281 excluded_path_prefixes: builtins.list[str] | None = None, 1282 page: int | None = None, 1283 page_size: int | None = None, 1284 ) -> SystemListResponse: 1285 """ 1286 List system configs 1287 Returns a paginated list of system (template) configs from the filesystem-backed 1288 manifest. Results are always ordered by `virtual_path` ascending. 1289 Filter by one or more config kinds using `kind` (single value) or `kinds` (array). 1290 Both filters may be supplied together for backward compatibility; `kinds` takes 1291 precedence when both are present. Exclude specific path namespaces with 1292 `excluded_path_prefixes`. 1293 Use `page` and `page_size` to paginate. Page size is clamped to a maximum of 200; 1294 requests exceeding this limit are silently clamped rather than rejected. 1295 1296 Args: 1297 kind: Filter results to a single config kind, e.g. `"Agent"` or `"APITool"`. Use `kinds` to filter by multiple kinds at once. 1298 kinds: Filter results to configs whose `kind` is in this list. When both `kind` and `kinds` are provided, `kinds` takes precedence. 1299 excluded_path_prefixes: Exclude configs whose `virtual_path` starts with any of the listed string prefixes. 1300 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1301 page_size: Number of results per page. Defaults to `50`; maximum is `200`. Values above the maximum are clamped to `200`. 1302 1303 Returns: 1304 Successful response 1305 """ 1306 query: dict[str, object] = {} 1307 if kind is not None: 1308 query["kind"] = kind 1309 if kinds is not None: 1310 query["kinds"] = kinds 1311 if excluded_path_prefixes is not None: 1312 query["excluded_path_prefixes"] = excluded_path_prefixes 1313 if page is not None: 1314 query["page"] = page 1315 if page_size is not None: 1316 query["page_size"] = page_size 1317 return self._http.request( 1318 "/api/v1/config/system", 1319 query=query, 1320 response_type=SystemListResponse, 1321 )
List system configs
Returns a paginated list of system (template) configs from the filesystem-backed
manifest. Results are always ordered by virtual_path ascending.
Filter by one or more config kinds using kind (single value) or kinds (array).
Both filters may be supplied together for backward compatibility; kinds takes
precedence when both are present. Exclude specific path namespaces with
excluded_path_prefixes.
Use page and page_size to paginate. Page size is clamped to a maximum of 200;
requests exceeding this limit are silently clamped rather than rejected.
Arguments:
- kind: Filter results to a single config kind, e.g.
"Agent"or"APITool". Usekindsto filter by multiple kinds at once. - kinds: Filter results to configs whose
kindis in this list. When bothkindandkindsare provided,kindstakes precedence. - excluded_path_prefixes: Exclude configs whose
virtual_pathstarts with any of the listed string prefixes. - page: Page number to retrieve, 1-indexed. Defaults to
1. - page_size: Number of results per page. Defaults to
50; maximum is200. Values above the maximum are clamped to200.
Returns:
Successful response
1323 def facets(self) -> ConfigFacets: 1324 """ 1325 Retrieve system config facets 1326 Returns the distinct `kind` values and leading `virtual_path` prefixes present 1327 in the system (template) config manifest, each accompanied by a count of matching 1328 configs. Use this data to populate filter UIs or to determine which config kinds 1329 are available before listing or cloning. 1330 The response reflects the filesystem-backed template manifest and does not include 1331 user- or team-owned configs. 1332 1333 Returns: 1334 Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs. 1335 """ 1336 return self._http.request("/api/v1/config/system/facets", response_type=ConfigFacets)
Retrieve system config facets
Returns the distinct kind values and leading virtual_path prefixes present
in the system (template) config manifest, each accompanied by a count of matching
configs. Use this data to populate filter UIs or to determine which config kinds
are available before listing or cloning.
The response reflects the filesystem-backed template manifest and does not include
user- or team-owned configs.
Returns:
Aggregated facet data containing distinct config kinds and path prefixes, each with a count of matching system configs.
1338 def get(self, system: str) -> Config: 1339 """ 1340 Retrieve a system config 1341 Returns a single system (template) config identified by its `virtual_path` or 1342 `lookup_key`. The `system` parameter value is URL-decoded before lookup, so 1343 path segments with special characters may be passed URL-encoded. 1344 System configs are filesystem-backed templates and are readable by any 1345 authenticated caller regardless of team or user ownership. Returns 404 when no 1346 system config matches the given identifier. 1347 1348 Args: 1349 system: Identifier of the system config to retrieve either its `virtual_path` or its `lookup_key`. May be URL-encoded. 1350 1351 Returns: 1352 The requested system config, including its current version and all metadata fields. 1353 """ 1354 return self._http.request(f"/api/v1/config/system/{system}", response_type=Config)
Retrieve a system config
Returns a single system (template) config identified by its virtual_path or
lookup_key. The system parameter value is URL-decoded before lookup, so
path segments with special characters may be passed URL-encoded.
System configs are filesystem-backed templates and are readable by any
authenticated caller regardless of team or user ownership. Returns 404 when no
system config matches the given identifier.
Arguments:
- system: Identifier of the system config to retrieve either its
virtual_pathor itslookup_key. May be URL-encoded.
Returns:
The requested system config, including its current version and all metadata fields.
1356 def clone(self, system: str, input: SystemCloneInput) -> Config: 1357 """ 1358 Clone a system config 1359 Creates a copy of a system (template) config and transfers ownership to a team 1360 or user. All dependencies bundled with the source config are cloned alongside it. 1361 Responds with HTTP 201 and the newly created config on success. 1362 You must specify exactly one destination owner via `team` or `user`. Callers 1363 authenticated as an app (developer portal) may omit the owner the clone is 1364 then scoped to the system owner automatically. 1365 Use `virtual_path` and `lookup_key` to override the corresponding fields on the 1366 clone; omitting them carries the values from the source. 1367 1368 Args: 1369 system: Identifier of the source system config either its `virtual_path` or its `lookup_key`. 1370 input: Request body. 1371 input.lookup_key: Override the `lookup_key` on the cloned config. When omitted, the source value is used. 1372 input.org: Organization ID (`org_...`) to scope the clone to. When set, must match the authenticated viewer's org. 1373 input.team: Team ID (`tea_...`) that will own the cloned config. Required unless `user` is provided or the caller is app-scoped. 1374 input.user: User ID (`usr_...`) that will own the cloned config. Required unless `team` is provided or the caller is app-scoped. 1375 input.virtual_path: Override the `virtual_path` on the cloned config. When omitted, the source value is used. 1376 1377 Returns: 1378 The newly created config, including all cloned fields and its assigned ID. 1379 """ 1380 return self._http.request( 1381 f"/api/v1/config/system/{system}/clone", 1382 method="POST", 1383 body=input, 1384 response_type=Config, 1385 )
Clone a system config
Creates a copy of a system (template) config and transfers ownership to a team
or user. All dependencies bundled with the source config are cloned alongside it.
Responds with HTTP 201 and the newly created config on success.
You must specify exactly one destination owner via team or user. Callers
authenticated as an app (developer portal) may omit the owner the clone is
then scoped to the system owner automatically.
Use virtual_path and lookup_key to override the corresponding fields on the
clone; omitting them carries the values from the source.
Arguments:
- system: Identifier of the source system config either its
virtual_pathor itslookup_key. - input: Request body.
- input.lookup_key: Override the
lookup_keyon the cloned config. When omitted, the source value is used. - input.org: Organization ID (
org_...) to scope the clone to. When set, must match the authenticated viewer's org. - input.team: Team ID (
tea_...) that will own the cloned config. Required unlessuseris provided or the caller is app-scoped. - input.user: User ID (
usr_...) that will own the cloned config. Required unlessteamis provided or the caller is app-scoped. - input.virtual_path: Override the
virtual_pathon the cloned config. When omitted, the source value is used.
Returns:
The newly created config, including all cloned fields and its assigned ID.
class
ConfigResource:
1388class ConfigResource: 1389 def __init__(self, http: SyncHttpClient): 1390 self._http = http 1391 self.kinds = KindResource(http) 1392 self.system = SystemResource(http) 1393 1394 def list( 1395 self, 1396 *, 1397 team: str | None = None, 1398 user: str | None = None, 1399 agent: str | None = None, 1400 kind: str | None = None, 1401 lookup_key: str | None = None, 1402 path_prefix: str | None = None, 1403 parents: builtins.list[str] | None = None, 1404 parent_solutions: builtins.list[str] | None = None, 1405 ) -> ConfigListResponse: 1406 """ 1407 List configs 1408 Returns all configs owned by the specified owner. Exactly one owner selector 1409 (`team`, `user`, or `agent`) must be provided. Passing an unknown or 1410 inaccessible owner returns an empty `data` array rather than an error, to 1411 avoid leaking information about which teams, users, or agents exist. 1412 Use the `kind`, `lookup_key`, `path_prefix`, `parents`, and 1413 `parent_solutions` params to narrow results. Private config kinds are always 1414 excluded from the response regardless of the viewer's permissions. 1415 Results are not paginated; all matching configs are returned in a single 1416 response. 1417 1418 Args: 1419 team: Team ID (`team_...`) whose configs to list. Mutually exclusive with `user` and `agent`. 1420 user: User ID (`usr_...`) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive with `team` and `agent`. 1421 agent: Agent ID (`agt_...`) whose configs to list. Mutually exclusive with `team` and `user`. 1422 kind: Filter results to configs of this kind, e.g. `"Agent"` or `"APITool"`. Omit to return configs of all non-private kinds. 1423 lookup_key: Filter to the config with exactly this `lookup_key`. Returns at most one result. 1424 path_prefix: Filter to configs whose `virtual_path` starts with this prefix, e.g. `"my-agent/"`. Useful for listing files within a folder. 1425 parents: Filter to configs that are children of any of the listed parent config IDs (`cfg_...`). Pass a single ID to retrieve all children of one bundle. 1426 parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (`cfg_...`). Useful for identifying all files that arrived with a given solution. 1427 1428 Returns: 1429 Successful response 1430 """ 1431 query: dict[str, object] = {} 1432 if team is not None: 1433 query["team"] = team 1434 if user is not None: 1435 query["user"] = user 1436 if agent is not None: 1437 query["agent"] = agent 1438 if kind is not None: 1439 query["kind"] = kind 1440 if lookup_key is not None: 1441 query["lookup_key"] = lookup_key 1442 if path_prefix is not None: 1443 query["path_prefix"] = path_prefix 1444 if parents is not None: 1445 query["parents"] = parents 1446 if parent_solutions is not None: 1447 query["parent_solutions"] = parent_solutions 1448 return self._http.request("/api/v1/config", query=query, response_type=ConfigListResponse) 1449 1450 def create(self, input: ConfigCreateInput) -> Config: 1451 """ 1452 Create a config 1453 Creates a new config and its first version. Returns 201 on success. 1454 A config is uniquely identified within an app + org scope by its 1455 `virtual_path` or `lookup_key`. Creating a config at a path that already 1456 exists (including archived configs) returns 409. To adopt an existing config 1457 at that path and re-own it instead, pass `take_ownership: true` this 1458 requires modify rights on the existing row (developer or all-powerful viewer). 1459 The owner is resolved from the explicit selector params (`team`, `user`, 1460 `agent`, or `system`). Developer and all-powerful viewers default to system 1461 ownership when no explicit selector is provided. Exactly one owner selector 1462 may be set; conflicting selectors return 422. 1463 Requires app scope. 1464 1465 Args: 1466 input: Request body. 1467 input.agent: Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`. 1468 input.change_description: Human-readable description of this initial version, stored on the version record. 1469 input.data: Arbitrary key-value metadata stored on the version alongside the content. 1470 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1471 input.kind: Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`. 1472 input.lookup_key: Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners. 1473 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. 1474 input.org: Organization ID (`org_...`) to scope the config to a specific org. 1475 input.parent: Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config. 1476 input.parent_solution: Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. 1477 input.raw_content: Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text. 1478 input.relative_path: Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set. 1479 input.system: Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`. 1480 input.take_ownership: When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). 1481 input.team: Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`. 1482 input.user: User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`. 1483 input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination. 1484 1485 Returns: 1486 The newly created config, including its first version. 1487 """ 1488 return self._http.request( 1489 "/api/v1/config", 1490 method="POST", 1491 body=input, 1492 response_type=Config, 1493 ) 1494 1495 def encrypt_secret(self, input: ConfigEncryptSecretInput) -> ConfigEncryptSecretResponse: 1496 """ 1497 Encrypt a secret for use in a config 1498 Encrypts a plaintext secret and returns a ciphertext string safe for 1499 embedding directly in config content using the `secret_value!` interpolation 1500 syntax. The ciphertext is bound to the app's (or org's) key-encryption key 1501 (KEK) so it can only be decrypted at runtime within the same scope. 1502 When `org` is provided, the KEK for that org is used; otherwise the 1503 viewer's own org KEK is used, falling back to the app-level KEK for viewers 1504 with no org context. 1505 The plaintext is never stored. Requires app scope. 1506 1507 Args: 1508 input: Request body. 1509 input.org: Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. 1510 input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned. 1511 1512 Returns: 1513 Successful response 1514 """ 1515 return self._http.request( 1516 "/api/v1/config/encrypt_secret", 1517 method="POST", 1518 body=input, 1519 response_type=ConfigEncryptSecretResponse, 1520 ) 1521 1522 def facets( 1523 self, 1524 *, 1525 app: str | None = None, 1526 team: str | None = None, 1527 user: str | None = None, 1528 org: str | None = None, 1529 ) -> ConfigFacets: 1530 """ 1531 List config facets 1532 Returns the distinct config kinds and leading `virtual_path` prefixes 1533 available to the viewer, each with a count of matching configs. Use this 1534 to populate filter UI dropdowns without making a full list request. 1535 The counts reflect every config the viewer can see in the requested scope, 1536 independent of any kind, path-prefix, or lookup-key filters that might be 1537 applied on a concurrent list request. This means the UI always shows every 1538 option the viewer could pick, not just the values on the current filtered page. 1539 Scoping follows the same rules as the list endpoint: developer and 1540 all-powerful viewers see facets across all owners in the app; org-scoped 1541 viewers receive their own configs' facets merged with system-owned facets; 1542 all other viewers see only their resolved owner's configs. 1543 1544 Args: 1545 app: App ID (`app_...`). Present when mounted under the developer scope; injected automatically. 1546 team: Team ID (`team_...`) to scope facets to that team's configs. Mutually exclusive with `user`. 1547 user: User ID (`usr_...`) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive with `team`. 1548 org: Organization ID (`org_...`) to narrow facets to configs belonging to that org. 1549 1550 Returns: 1551 Distinct config kinds and `virtual_path` prefixes with per-value counts. 1552 """ 1553 query: dict[str, object] = {} 1554 if app is not None: 1555 query["app"] = app 1556 if team is not None: 1557 query["team"] = team 1558 if user is not None: 1559 query["user"] = user 1560 if org is not None: 1561 query["org"] = org 1562 return self._http.request("/api/v1/config/facets", query=query, response_type=ConfigFacets) 1563 1564 def validate(self, input: ConfigValidateInput) -> ValidationResult: 1565 """ 1566 Validate config content 1567 Validates raw config content against the schema for a given config kind 1568 without saving anything. Returns a structured result indicating whether the 1569 content is valid and, if not, a list of error messages. 1570 Use this endpoint to give users early feedback before calling create or 1571 update. The owner context is used for any kind-specific validation rules that 1572 are owner-aware; provide the same owner you intend to use on the write call. 1573 Requires app scope. 1574 1575 Args: 1576 input: Request body. 1577 input.agent: Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`. 1578 input.data: Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content. 1579 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1580 input.kind: Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`. 1581 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation. 1582 input.raw_content: Raw content bytes to validate. Parsed according to `mime_type` before schema validation. 1583 input.team: Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`. 1584 input.user: User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`. 1585 1586 Returns: 1587 Validation outcome. Always HTTP 200; check the `valid` field to determine success. Includes `errors` when `valid` is `false`. 1588 """ 1589 return self._http.request( 1590 "/api/v1/config/validate", 1591 method="POST", 1592 body=input, 1593 response_type=ValidationResult, 1594 ) 1595 1596 def delete(self, config: str) -> None: 1597 """ 1598 Delete a config 1599 Permanently deletes a config and all its associated versions. This action is 1600 irreversible. To soft-delete a config while retaining its history, use the 1601 archive endpoint instead. 1602 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1603 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1604 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1605 passing an owner selector when addressing by ID returns 422. 1606 Returns 204 No Content on success. Requires app scope. The viewer must have 1607 modify rights on the config. 1608 1609 Args: 1610 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1611 1612 Returns: 1613 Empty body. HTTP 204 indicates the config and all its versions were permanently deleted. 1614 """ 1615 self._http.request(f"/api/v1/config/{config}", method="DELETE") 1616 1617 def get( 1618 self, 1619 config: str, 1620 *, 1621 team: str | None = None, 1622 user: str | None = None, 1623 agent: str | None = None, 1624 system: bool | None = None, 1625 org: str | None = None, 1626 ) -> Config: 1627 """ 1628 Retrieve a config 1629 Returns a single config identified by its ID, `virtual_path`, or 1630 `lookup_key`. The config object includes its current version metadata but 1631 not the raw content bytes; use the content endpoint to fetch the raw content. 1632 When addressing by `lookup_key` or `virtual_path`, you must supply exactly 1633 one owner selector (`team`, `user`, `agent`, or `system`). Passing an owner 1634 selector when addressing by ID (`cfg_...`) returns 422. Both `not_found` 1635 and `forbidden` outcomes are surfaced as 404 to avoid leaking config 1636 existence. 1637 Requires app scope. 1638 1639 Args: 1640 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1641 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1642 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1643 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1644 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1645 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1646 1647 Returns: 1648 The requested config object. 1649 """ 1650 query: dict[str, object] = {} 1651 if team is not None: 1652 query["team"] = team 1653 if user is not None: 1654 query["user"] = user 1655 if agent is not None: 1656 query["agent"] = agent 1657 if system is not None: 1658 query["system"] = system 1659 if org is not None: 1660 query["org"] = org 1661 return self._http.request(f"/api/v1/config/{config}", query=query, response_type=Config) 1662 1663 def update(self, config: str, input: ConfigUpdateInput) -> Config: 1664 """ 1665 Update a config 1666 Updates an existing config. When `raw_content` is provided, a new version is 1667 created and becomes the current version. When `raw_content` is omitted, only 1668 metadata fields (`virtual_path`, `lookup_key`, `relative_path`, 1669 `parent_solution`) are updated without creating a new version. 1670 Use `expected_version` for optimistic concurrency control: if the config's 1671 current version number does not match the supplied value the request returns 1672 409. This prevents overwriting concurrent edits. 1673 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1674 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1675 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1676 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1677 Requires app scope. The viewer must have modify rights on the config. 1678 1679 Args: 1680 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1681 input: Request body. 1682 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1683 input.change_description: Human-readable description of this update, stored on the new version record. 1684 input.data: Arbitrary key-value metadata to store on the new version alongside the content. 1685 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1686 input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking. 1687 input.lookup_key: New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted. 1688 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field. 1689 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1690 input.parent_solution: Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string. 1691 input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version. 1692 input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`. 1693 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1694 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1695 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1696 input.virtual_path: New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted. 1697 1698 Returns: 1699 The config reflecting the applied update. 1700 """ 1701 return self._http.request( 1702 f"/api/v1/config/{config}", 1703 method="PATCH", 1704 body=input, 1705 response_type=Config, 1706 ) 1707 1708 def archive(self, config: str, input: ConfigArchiveInput) -> Config: 1709 """ 1710 Archive a config 1711 Soft-deletes a config by marking it as archived. Archived configs are hidden 1712 from list and show endpoints but are not permanently removed; use the 1713 unarchive endpoint to restore one, or the delete endpoint for permanent 1714 removal. 1715 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1716 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1717 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1718 passing an owner selector when addressing by ID returns 422. 1719 Requires app scope. The viewer must have modify rights on the config. 1720 1721 Args: 1722 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. `virtual_path` values should be URL-encoded if they contain slashes. 1723 input: Request body. 1724 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1725 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. 1726 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1727 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1728 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1729 1730 Returns: 1731 The config in its newly archived state. 1732 """ 1733 return self._http.request( 1734 f"/api/v1/config/{config}/archive", 1735 method="POST", 1736 body=input, 1737 response_type=Config, 1738 ) 1739 1740 def change_owner(self, config: str, input: ConfigChangeOwnerInput) -> Config: 1741 """ 1742 Transfer ownership of a config 1743 Transfers a config to a new owner (`team`, `user`, `agent`, or `system`). 1744 Exactly one of the new-owner selectors must be provided. The config must be 1745 addressed by its ID (`cfg_...` or UUID); `virtual_path` and `lookup_key` 1746 are not accepted to avoid ambiguity look up the ID first if needed. 1747 For non-system targets the new owner's org is derived automatically from the 1748 target entity; supplying `org` in that case returns 422. For `system:true` 1749 targets, `org` controls the resulting org scope: omit to keep the existing 1750 `org_id`, supply a value to set a specific org, or pass `null`/blank to make 1751 the config app-level (operator viewers only). 1752 Operator viewers (developer credentials or all-powerful viewers) may transfer 1753 to any owner. All other viewers are restricted to owners they can themselves 1754 access (team membership, user identity, agent scope, or `system` with the 1755 appropriate privilege). 1756 Requires app scope. The viewer must have modify rights on the config. 1757 1758 Args: 1759 config: Config ID in id-form: `cfg_...` or a UUID. `lookup_key` and `virtual_path` are not accepted retrieve the config ID first if you only have a path. 1760 input: Request body. 1761 input.agent: New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`. 1762 input.org: Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422. 1763 input.system: Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`. 1764 input.team: New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`. 1765 input.user: New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`. 1766 1767 Returns: 1768 The config reflecting its new ownership. 1769 """ 1770 return self._http.request( 1771 f"/api/v1/config/{config}/change_owner", 1772 method="POST", 1773 body=input, 1774 response_type=Config, 1775 ) 1776 1777 def content( 1778 self, 1779 config: str, 1780 *, 1781 team: str | None = None, 1782 user: str | None = None, 1783 agent: str | None = None, 1784 system: bool | None = None, 1785 org: str | None = None, 1786 format: str | None = None, 1787 inject_protected_fields: bool | None = None, 1788 ) -> dict[str, str]: 1789 """ 1790 Retrieve a config's raw content 1791 Returns the raw byte content of a config's current version. The response 1792 `Content-Type` header reflects the config's stored MIME type unless a 1793 `format` conversion is requested. 1794 Pass `format: "yaml"` or `format: "json"` to convert between YAML and JSON 1795 on the fly. Conversion is only supported between these two formats; requesting 1796 a conversion that is not possible returns 400. 1797 By default, `virtual_path` and other platform-injected protected fields are 1798 embedded in the returned content. Set `inject_protected_fields: false` to 1799 return the stored raw bytes exactly as written. 1800 The config may be addressed by ID (`cfg_...`), `virtual_path`, or 1801 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, exactly one 1802 owner selector (`team`, `user`, `agent`, or `system`) is required. 1803 1804 Args: 1805 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1806 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1807 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1808 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1809 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1810 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1811 format: Output format for content conversion. One of `"yaml"` or `"json"`. Omit to return the content in its stored format. Returns 400 if conversion is not possible. 1812 inject_protected_fields: Whether to inject platform-managed protected fields (such as `virtual_path`) into the returned content. Defaults to `true`. Set to `false` to receive the raw stored bytes. 1813 1814 Returns: 1815 Raw config content in the stored or requested format. 1816 """ 1817 query: dict[str, object] = {} 1818 if team is not None: 1819 query["team"] = team 1820 if user is not None: 1821 query["user"] = user 1822 if agent is not None: 1823 query["agent"] = agent 1824 if system is not None: 1825 query["system"] = system 1826 if org is not None: 1827 query["org"] = org 1828 if format is not None: 1829 query["format"] = format 1830 if inject_protected_fields is not None: 1831 query["inject_protected_fields"] = inject_protected_fields 1832 return self._http.request_raw(f"/api/v1/config/{config}/content", query=query) 1833 1834 def unarchive(self, config: str, input: ConfigUnarchiveInput) -> Config: 1835 """ 1836 Unarchive a config 1837 Restores a previously archived config, making it visible again in list and 1838 show responses. The config's content and version history are unchanged. 1839 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1840 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1841 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1842 passing an owner selector when addressing by ID returns 422. 1843 Requires app scope. The viewer must have modify rights on the config. 1844 1845 Args: 1846 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1847 input: Request body. 1848 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1849 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1850 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1851 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1852 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1853 1854 Returns: 1855 The config in its newly restored (active) state. 1856 """ 1857 return self._http.request( 1858 f"/api/v1/config/{config}/unarchive", 1859 method="POST", 1860 body=input, 1861 response_type=Config, 1862 ) 1863 1864 def versions( 1865 self, 1866 config: str, 1867 *, 1868 team: str | None = None, 1869 user: str | None = None, 1870 agent: str | None = None, 1871 system: bool | None = None, 1872 org: str | None = None, 1873 ) -> ConfigVersionsResponse: 1874 """ 1875 List a config's version history 1876 Returns all versions of a config in the order they were created, most recent 1877 first. Each version includes its version number, content metadata, and change 1878 description. The raw content bytes for a specific version are not included; 1879 use the content endpoint to fetch them. 1880 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1881 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1882 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1883 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1884 Requires app scope. 1885 1886 Args: 1887 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1888 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1889 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1890 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1891 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1892 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1893 1894 Returns: 1895 Successful response 1896 """ 1897 query: dict[str, object] = {} 1898 if team is not None: 1899 query["team"] = team 1900 if user is not None: 1901 query["user"] = user 1902 if agent is not None: 1903 query["agent"] = agent 1904 if system is not None: 1905 query["system"] = system 1906 if org is not None: 1907 query["org"] = org 1908 return self._http.request( 1909 f"/api/v1/config/{config}/versions", 1910 query=query, 1911 response_type=ConfigVersionsResponse, 1912 )
ConfigResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, *, team: str | None = None, user: str | None = None, agent: str | None = None, kind: str | None = None, lookup_key: str | None = None, path_prefix: str | None = None, parents: list[str] | None = None, parent_solutions: list[str] | None = None) -> ConfigListResponse:
1394 def list( 1395 self, 1396 *, 1397 team: str | None = None, 1398 user: str | None = None, 1399 agent: str | None = None, 1400 kind: str | None = None, 1401 lookup_key: str | None = None, 1402 path_prefix: str | None = None, 1403 parents: builtins.list[str] | None = None, 1404 parent_solutions: builtins.list[str] | None = None, 1405 ) -> ConfigListResponse: 1406 """ 1407 List configs 1408 Returns all configs owned by the specified owner. Exactly one owner selector 1409 (`team`, `user`, or `agent`) must be provided. Passing an unknown or 1410 inaccessible owner returns an empty `data` array rather than an error, to 1411 avoid leaking information about which teams, users, or agents exist. 1412 Use the `kind`, `lookup_key`, `path_prefix`, `parents`, and 1413 `parent_solutions` params to narrow results. Private config kinds are always 1414 excluded from the response regardless of the viewer's permissions. 1415 Results are not paginated; all matching configs are returned in a single 1416 response. 1417 1418 Args: 1419 team: Team ID (`team_...`) whose configs to list. Mutually exclusive with `user` and `agent`. 1420 user: User ID (`usr_...`) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive with `team` and `agent`. 1421 agent: Agent ID (`agt_...`) whose configs to list. Mutually exclusive with `team` and `user`. 1422 kind: Filter results to configs of this kind, e.g. `"Agent"` or `"APITool"`. Omit to return configs of all non-private kinds. 1423 lookup_key: Filter to the config with exactly this `lookup_key`. Returns at most one result. 1424 path_prefix: Filter to configs whose `virtual_path` starts with this prefix, e.g. `"my-agent/"`. Useful for listing files within a folder. 1425 parents: Filter to configs that are children of any of the listed parent config IDs (`cfg_...`). Pass a single ID to retrieve all children of one bundle. 1426 parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (`cfg_...`). Useful for identifying all files that arrived with a given solution. 1427 1428 Returns: 1429 Successful response 1430 """ 1431 query: dict[str, object] = {} 1432 if team is not None: 1433 query["team"] = team 1434 if user is not None: 1435 query["user"] = user 1436 if agent is not None: 1437 query["agent"] = agent 1438 if kind is not None: 1439 query["kind"] = kind 1440 if lookup_key is not None: 1441 query["lookup_key"] = lookup_key 1442 if path_prefix is not None: 1443 query["path_prefix"] = path_prefix 1444 if parents is not None: 1445 query["parents"] = parents 1446 if parent_solutions is not None: 1447 query["parent_solutions"] = parent_solutions 1448 return self._http.request("/api/v1/config", query=query, response_type=ConfigListResponse)
List configs
Returns all configs owned by the specified owner. Exactly one owner selector
(team, user, or agent) must be provided. Passing an unknown or
inaccessible owner returns an empty data array rather than an error, to
avoid leaking information about which teams, users, or agents exist.
Use the kind, lookup_key, path_prefix, parents, and
parent_solutions params to narrow results. Private config kinds are always
excluded from the response regardless of the viewer's permissions.
Results are not paginated; all matching configs are returned in a single
response.
Arguments:
- team: Team ID (
team_...) whose configs to list. Mutually exclusive withuserandagent. - user: User ID (
usr_...) whose configs to list. Defaults to the current user when the viewer is a user and no owner selector is provided. Mutually exclusive withteamandagent. - agent: Agent ID (
agt_...) whose configs to list. Mutually exclusive withteamanduser. - kind: Filter results to configs of this kind, e.g.
"Agent"or"APITool". Omit to return configs of all non-private kinds. - lookup_key: Filter to the config with exactly this
lookup_key. Returns at most one result. - path_prefix: Filter to configs whose
virtual_pathstarts with this prefix, e.g."my-agent/". Useful for listing files within a folder. - parents: Filter to configs that are children of any of the listed parent config IDs (
cfg_...). Pass a single ID to retrieve all children of one bundle. - parent_solutions: Filter to configs that were imported as part of any of the listed solution config IDs (
cfg_...). Useful for identifying all files that arrived with a given solution.
Returns:
Successful response
1450 def create(self, input: ConfigCreateInput) -> Config: 1451 """ 1452 Create a config 1453 Creates a new config and its first version. Returns 201 on success. 1454 A config is uniquely identified within an app + org scope by its 1455 `virtual_path` or `lookup_key`. Creating a config at a path that already 1456 exists (including archived configs) returns 409. To adopt an existing config 1457 at that path and re-own it instead, pass `take_ownership: true` this 1458 requires modify rights on the existing row (developer or all-powerful viewer). 1459 The owner is resolved from the explicit selector params (`team`, `user`, 1460 `agent`, or `system`). Developer and all-powerful viewers default to system 1461 ownership when no explicit selector is provided. Exactly one owner selector 1462 may be set; conflicting selectors return 422. 1463 Requires app scope. 1464 1465 Args: 1466 input: Request body. 1467 input.agent: Agent ID (`agt_...`) to assign as the config owner. Mutually exclusive with `team`, `user`, and `system`. 1468 input.change_description: Human-readable description of this initial version, stored on the version record. 1469 input.data: Arbitrary key-value metadata stored on the version alongside the content. 1470 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1471 input.kind: Config kind that determines the schema and behavior of the config, e.g. `"Agent"` or `"APITool"`. 1472 input.lookup_key: Optional stable key for looking up this config independent of its `virtual_path`. Must be unique within the app + org scope across all owners. 1473 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. 1474 input.org: Organization ID (`org_...`) to scope the config to a specific org. 1475 input.parent: Parent config ID (`cfg_...`) for bundle children, e.g. files belonging to a Skill. Required together with `relative_path` when creating a child config. 1476 input.parent_solution: Solution config ID (`cfg_...`) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. 1477 input.raw_content: Raw content bytes for the first version. Accepted formats depend on `mime_type`; typical values are YAML or JSON text. 1478 input.relative_path: Path of this config within its parent bundle, e.g. `"prompts/system.md"`. Required when `parent` is set. 1479 input.system: Set `true` to create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive with `team`, `user`, and `agent`. 1480 input.take_ownership: When `true` and a config already exists at the specified `virtual_path` or `lookup_key` under a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). 1481 input.team: Team ID (`team_...`) to assign as the config owner. Mutually exclusive with `user`, `agent`, and `system`. 1482 input.user: User ID (`usr_...`) to assign as the config owner. Mutually exclusive with `team`, `agent`, and `system`. 1483 input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g. `"my-agent/v1"`. Must be unique within the app + org + owner combination. 1484 1485 Returns: 1486 The newly created config, including its first version. 1487 """ 1488 return self._http.request( 1489 "/api/v1/config", 1490 method="POST", 1491 body=input, 1492 response_type=Config, 1493 )
Create a config
Creates a new config and its first version. Returns 201 on success.
A config is uniquely identified within an app + org scope by its
virtual_path or lookup_key. Creating a config at a path that already
exists (including archived configs) returns 409. To adopt an existing config
at that path and re-own it instead, pass take_ownership: true this
requires modify rights on the existing row (developer or all-powerful viewer).
The owner is resolved from the explicit selector params (team, user,
agent, or system). Developer and all-powerful viewers default to system
ownership when no explicit selector is provided. Exactly one owner selector
may be set; conflicting selectors return 422.
Requires app scope.
Arguments:
- input: Request body.
- input.agent: Agent ID (
agt_...) to assign as the config owner. Mutually exclusive withteam,user, andsystem. - input.change_description: Human-readable description of this initial version, stored on the version record.
- input.data: Arbitrary key-value metadata stored on the version alongside the content.
- input.data_encoding: Encoding of
raw_content. Omit or set"raw"for literal content; set"base64"when sending binary content such as images or PDFs in JSON. - input.kind: Config kind that determines the schema and behavior of the config, e.g.
"Agent"or"APITool". - input.lookup_key: Optional stable key for looking up this config independent of its
virtual_path. Must be unique within the app + org scope across all owners. - input.mime_type: MIME type of
raw_content, e.g."application/x-yaml"or"application/json". - input.org: Organization ID (
org_...) to scope the config to a specific org. - input.parent: Parent config ID (
cfg_...) for bundle children, e.g. files belonging to a Skill. Required together withrelative_pathwhen creating a child config. - input.parent_solution: Solution config ID (
cfg_...) that this config was imported with. Records provenance for configs that arrive as part of a solution bundle. - input.raw_content: Raw content bytes for the first version. Accepted formats depend on
mime_type; typical values are YAML or JSON text. - input.relative_path: Path of this config within its parent bundle, e.g.
"prompts/system.md". Required whenparentis set. - input.system: Set
trueto create a system-owned config (no team, user, or agent owner). Requires a developer, all-powerful, or app system-user viewer, or an org admin creating an org-scoped system config. Mutually exclusive withteam,user, andagent. - input.take_ownership: When
trueand a config already exists at the specifiedvirtual_pathorlookup_keyunder a different owner, adopt that config rather than returning 409: the existing row is re-owned to the requested owner, unarchived if necessary, and this content is saved as its next version. Requires modify rights on the existing row (developer or all-powerful viewer). - input.team: Team ID (
team_...) to assign as the config owner. Mutually exclusive withuser,agent, andsystem. - input.user: User ID (
usr_...) to assign as the config owner. Mutually exclusive withteam,agent, andsystem. - input.virtual_path: Human-readable path that uniquely identifies the config within its owner scope, e.g.
"my-agent/v1". Must be unique within the app + org + owner combination.
Returns:
The newly created config, including its first version.
1495 def encrypt_secret(self, input: ConfigEncryptSecretInput) -> ConfigEncryptSecretResponse: 1496 """ 1497 Encrypt a secret for use in a config 1498 Encrypts a plaintext secret and returns a ciphertext string safe for 1499 embedding directly in config content using the `secret_value!` interpolation 1500 syntax. The ciphertext is bound to the app's (or org's) key-encryption key 1501 (KEK) so it can only be decrypted at runtime within the same scope. 1502 When `org` is provided, the KEK for that org is used; otherwise the 1503 viewer's own org KEK is used, falling back to the app-level KEK for viewers 1504 with no org context. 1505 The plaintext is never stored. Requires app scope. 1506 1507 Args: 1508 input: Request body. 1509 input.org: Organization ID (`org_...`) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. 1510 input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned. 1511 1512 Returns: 1513 Successful response 1514 """ 1515 return self._http.request( 1516 "/api/v1/config/encrypt_secret", 1517 method="POST", 1518 body=input, 1519 response_type=ConfigEncryptSecretResponse, 1520 )
Encrypt a secret for use in a config
Encrypts a plaintext secret and returns a ciphertext string safe for
embedding directly in config content using the secret_value! interpolation
syntax. The ciphertext is bound to the app's (or org's) key-encryption key
(KEK) so it can only be decrypted at runtime within the same scope.
When org is provided, the KEK for that org is used; otherwise the
viewer's own org KEK is used, falling back to the app-level KEK for viewers
with no org context.
The plaintext is never stored. Requires app scope.
Arguments:
- input: Request body.
- input.org: Organization ID (
org_...) whose KEK to use for encryption. Overrides the viewer's own org. Omit to use the viewer's org KEK, or the app-level KEK when the viewer has no org context. - input.plaintext: The secret value to encrypt. Never stored; only the resulting ciphertext is returned.
Returns:
Successful response
def
facets( self, *, app: str | None = None, team: str | None = None, user: str | None = None, org: str | None = None) -> archastro.platform.types.config.ConfigFacets:
1522 def facets( 1523 self, 1524 *, 1525 app: str | None = None, 1526 team: str | None = None, 1527 user: str | None = None, 1528 org: str | None = None, 1529 ) -> ConfigFacets: 1530 """ 1531 List config facets 1532 Returns the distinct config kinds and leading `virtual_path` prefixes 1533 available to the viewer, each with a count of matching configs. Use this 1534 to populate filter UI dropdowns without making a full list request. 1535 The counts reflect every config the viewer can see in the requested scope, 1536 independent of any kind, path-prefix, or lookup-key filters that might be 1537 applied on a concurrent list request. This means the UI always shows every 1538 option the viewer could pick, not just the values on the current filtered page. 1539 Scoping follows the same rules as the list endpoint: developer and 1540 all-powerful viewers see facets across all owners in the app; org-scoped 1541 viewers receive their own configs' facets merged with system-owned facets; 1542 all other viewers see only their resolved owner's configs. 1543 1544 Args: 1545 app: App ID (`app_...`). Present when mounted under the developer scope; injected automatically. 1546 team: Team ID (`team_...`) to scope facets to that team's configs. Mutually exclusive with `user`. 1547 user: User ID (`usr_...`) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive with `team`. 1548 org: Organization ID (`org_...`) to narrow facets to configs belonging to that org. 1549 1550 Returns: 1551 Distinct config kinds and `virtual_path` prefixes with per-value counts. 1552 """ 1553 query: dict[str, object] = {} 1554 if app is not None: 1555 query["app"] = app 1556 if team is not None: 1557 query["team"] = team 1558 if user is not None: 1559 query["user"] = user 1560 if org is not None: 1561 query["org"] = org 1562 return self._http.request("/api/v1/config/facets", query=query, response_type=ConfigFacets)
List config facets
Returns the distinct config kinds and leading virtual_path prefixes
available to the viewer, each with a count of matching configs. Use this
to populate filter UI dropdowns without making a full list request.
The counts reflect every config the viewer can see in the requested scope,
independent of any kind, path-prefix, or lookup-key filters that might be
applied on a concurrent list request. This means the UI always shows every
option the viewer could pick, not just the values on the current filtered page.
Scoping follows the same rules as the list endpoint: developer and
all-powerful viewers see facets across all owners in the app; org-scoped
viewers receive their own configs' facets merged with system-owned facets;
all other viewers see only their resolved owner's configs.
Arguments:
- app: App ID (
app_...). Present when mounted under the developer scope; injected automatically. - team: Team ID (
team_...) to scope facets to that team's configs. Mutually exclusive withuser. - user: User ID (
usr_...) to scope facets to that user's configs. Defaults to the current user when the viewer is a user and no selector is provided. Mutually exclusive withteam. - org: Organization ID (
org_...) to narrow facets to configs belonging to that org.
Returns:
Distinct config kinds and
virtual_pathprefixes with per-value counts.
def
validate( self, input: ConfigValidateInput) -> archastro.platform.types.common.ValidationResult:
1564 def validate(self, input: ConfigValidateInput) -> ValidationResult: 1565 """ 1566 Validate config content 1567 Validates raw config content against the schema for a given config kind 1568 without saving anything. Returns a structured result indicating whether the 1569 content is valid and, if not, a list of error messages. 1570 Use this endpoint to give users early feedback before calling create or 1571 update. The owner context is used for any kind-specific validation rules that 1572 are owner-aware; provide the same owner you intend to use on the write call. 1573 Requires app scope. 1574 1575 Args: 1576 input: Request body. 1577 input.agent: Agent ID (`agt_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `user`. 1578 input.data: Optional metadata used by kind-specific validation. File and Image configs require `data.name` when validating direct binary content. 1579 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1580 input.kind: Config kind whose schema the content is validated against, e.g. `"Agent"` or `"APITool"`. 1581 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Used to parse the content before validation. 1582 input.raw_content: Raw content bytes to validate. Parsed according to `mime_type` before schema validation. 1583 input.team: Team ID (`team_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `user` and `agent`. 1584 input.user: User ID (`usr_...`) that would own the config. Used for owner-aware validation rules. Mutually exclusive with `team` and `agent`. 1585 1586 Returns: 1587 Validation outcome. Always HTTP 200; check the `valid` field to determine success. Includes `errors` when `valid` is `false`. 1588 """ 1589 return self._http.request( 1590 "/api/v1/config/validate", 1591 method="POST", 1592 body=input, 1593 response_type=ValidationResult, 1594 )
Validate config content Validates raw config content against the schema for a given config kind without saving anything. Returns a structured result indicating whether the content is valid and, if not, a list of error messages. Use this endpoint to give users early feedback before calling create or update. The owner context is used for any kind-specific validation rules that are owner-aware; provide the same owner you intend to use on the write call. Requires app scope.
Arguments:
- input: Request body.
- input.agent: Agent ID (
agt_...) that would own the config. Used for owner-aware validation rules. Mutually exclusive withteamanduser. - input.data: Optional metadata used by kind-specific validation. File and Image configs require
data.namewhen validating direct binary content. - input.data_encoding: Encoding of
raw_content. Omit or set"raw"for literal content; set"base64"when sending binary content such as images or PDFs in JSON. - input.kind: Config kind whose schema the content is validated against, e.g.
"Agent"or"APITool". - input.mime_type: MIME type of
raw_content, e.g."application/x-yaml"or"application/json". Used to parse the content before validation. - input.raw_content: Raw content bytes to validate. Parsed according to
mime_typebefore schema validation. - input.team: Team ID (
team_...) that would own the config. Used for owner-aware validation rules. Mutually exclusive withuserandagent. - input.user: User ID (
usr_...) that would own the config. Used for owner-aware validation rules. Mutually exclusive withteamandagent.
Returns:
Validation outcome. Always HTTP 200; check the
validfield to determine success. Includeserrorswhenvalidisfalse.
def
delete(self, config: str) -> None:
1596 def delete(self, config: str) -> None: 1597 """ 1598 Delete a config 1599 Permanently deletes a config and all its associated versions. This action is 1600 irreversible. To soft-delete a config while retaining its history, use the 1601 archive endpoint instead. 1602 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1603 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1604 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1605 passing an owner selector when addressing by ID returns 422. 1606 Returns 204 No Content on success. Requires app scope. The viewer must have 1607 modify rights on the config. 1608 1609 Args: 1610 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1611 1612 Returns: 1613 Empty body. HTTP 204 indicates the config and all its versions were permanently deleted. 1614 """ 1615 self._http.request(f"/api/v1/config/{config}", method="DELETE")
Delete a config
Permanently deletes a config and all its associated versions. This action is
irreversible. To soft-delete a config while retaining its history, use the
archive endpoint instead.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system);
passing an owner selector when addressing by ID returns 422.
Returns 204 No Content on success. Requires app scope. The viewer must have
modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes.
Returns:
Empty body. HTTP 204 indicates the config and all its versions were permanently deleted.
def
get( self, config: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, system: bool | None = None, org: str | None = None) -> archastro.platform.types.config.Config:
1617 def get( 1618 self, 1619 config: str, 1620 *, 1621 team: str | None = None, 1622 user: str | None = None, 1623 agent: str | None = None, 1624 system: bool | None = None, 1625 org: str | None = None, 1626 ) -> Config: 1627 """ 1628 Retrieve a config 1629 Returns a single config identified by its ID, `virtual_path`, or 1630 `lookup_key`. The config object includes its current version metadata but 1631 not the raw content bytes; use the content endpoint to fetch the raw content. 1632 When addressing by `lookup_key` or `virtual_path`, you must supply exactly 1633 one owner selector (`team`, `user`, `agent`, or `system`). Passing an owner 1634 selector when addressing by ID (`cfg_...`) returns 422. Both `not_found` 1635 and `forbidden` outcomes are surfaced as 404 to avoid leaking config 1636 existence. 1637 Requires app scope. 1638 1639 Args: 1640 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1641 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1642 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1643 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1644 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1645 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1646 1647 Returns: 1648 The requested config object. 1649 """ 1650 query: dict[str, object] = {} 1651 if team is not None: 1652 query["team"] = team 1653 if user is not None: 1654 query["user"] = user 1655 if agent is not None: 1656 query["agent"] = agent 1657 if system is not None: 1658 query["system"] = system 1659 if org is not None: 1660 query["org"] = org 1661 return self._http.request(f"/api/v1/config/{config}", query=query, response_type=Config)
Retrieve a config
Returns a single config identified by its ID, virtual_path, or
lookup_key. The config object includes its current version metadata but
not the raw content bytes; use the content endpoint to fetch the raw content.
When addressing by lookup_key or virtual_path, you must supply exactly
one owner selector (team, user, agent, or system). Passing an owner
selector when addressing by ID (cfg_...) returns 422. Both not_found
and forbidden outcomes are surfaced as 404 to avoid leaking config
existence.
Requires app scope.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org.
Returns:
The requested config object.
1663 def update(self, config: str, input: ConfigUpdateInput) -> Config: 1664 """ 1665 Update a config 1666 Updates an existing config. When `raw_content` is provided, a new version is 1667 created and becomes the current version. When `raw_content` is omitted, only 1668 metadata fields (`virtual_path`, `lookup_key`, `relative_path`, 1669 `parent_solution`) are updated without creating a new version. 1670 Use `expected_version` for optimistic concurrency control: if the config's 1671 current version number does not match the supplied value the request returns 1672 409. This prevents overwriting concurrent edits. 1673 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1674 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1675 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1676 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1677 Requires app scope. The viewer must have modify rights on the config. 1678 1679 Args: 1680 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1681 input: Request body. 1682 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1683 input.change_description: Human-readable description of this update, stored on the new version record. 1684 input.data: Arbitrary key-value metadata to store on the new version alongside the content. 1685 input.data_encoding: Encoding of `raw_content`. Omit or set `"raw"` for literal content; set `"base64"` when sending binary content such as images or PDFs in JSON. 1686 input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking. 1687 input.lookup_key: New `lookup_key` for the config. Updates the key without creating a new version when `raw_content` is omitted. 1688 input.mime_type: MIME type of `raw_content`, e.g. `"application/x-yaml"` or `"application/json"`. Defaults to the existing MIME type when `raw_content` is provided without this field. 1689 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1690 input.parent_solution: Solution config ID (`cfg_...`) to set as the config's parent solution provenance. Clears the value when set to an empty string. 1691 input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version. 1692 input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a `parent`. 1693 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1694 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1695 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1696 input.virtual_path: New `virtual_path` for the config. Updates the path without creating a new version when `raw_content` is omitted. 1697 1698 Returns: 1699 The config reflecting the applied update. 1700 """ 1701 return self._http.request( 1702 f"/api/v1/config/{config}", 1703 method="PATCH", 1704 body=input, 1705 response_type=Config, 1706 )
Update a config
Updates an existing config. When raw_content is provided, a new version is
created and becomes the current version. When raw_content is omitted, only
metadata fields (virtual_path, lookup_key, relative_path,
parent_solution) are updated without creating a new version.
Use expected_version for optimistic concurrency control: if the config's
current version number does not match the supplied value the request returns
- This prevents overwriting concurrent edits.
The config may be addressed by its ID (
cfg_...),virtual_path, orlookup_key. When addressing bylookup_keyorvirtual_path, you must supply exactly one owner selector (team,user,agent, orsystem). Bothnot_foundandforbiddenoutcomes are surfaced as 404. Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - input: Request body.
- input.agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.change_description: Human-readable description of this update, stored on the new version record.
- input.data: Arbitrary key-value metadata to store on the new version alongside the content.
- input.data_encoding: Encoding of
raw_content. Omit or set"raw"for literal content; set"base64"when sending binary content such as images or PDFs in JSON. - input.expected_version: Version number the caller expects to be current. If the config's actual current version does not match, the request returns 409 to signal a concurrent modification. Omit to skip optimistic locking.
- input.lookup_key: New
lookup_keyfor the config. Updates the key without creating a new version whenraw_contentis omitted. - input.mime_type: MIME type of
raw_content, e.g."application/x-yaml"or"application/json". Defaults to the existing MIME type whenraw_contentis provided without this field. - input.org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. - input.parent_solution: Solution config ID (
cfg_...) to set as the config's parent solution provenance. Clears the value when set to an empty string. - input.raw_content: New raw content bytes for the config. When provided, a new version is created. Omit to perform a metadata-only update without incrementing the version.
- input.relative_path: Updated path of this config within its parent bundle. Only meaningful when the config has a
parent. - input.system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - input.team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.virtual_path: New
virtual_pathfor the config. Updates the path without creating a new version whenraw_contentis omitted.
Returns:
The config reflecting the applied update.
def
archive( self, config: str, input: ConfigArchiveInput) -> archastro.platform.types.config.Config:
1708 def archive(self, config: str, input: ConfigArchiveInput) -> Config: 1709 """ 1710 Archive a config 1711 Soft-deletes a config by marking it as archived. Archived configs are hidden 1712 from list and show endpoints but are not permanently removed; use the 1713 unarchive endpoint to restore one, or the delete endpoint for permanent 1714 removal. 1715 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1716 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1717 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1718 passing an owner selector when addressing by ID returns 422. 1719 Requires app scope. The viewer must have modify rights on the config. 1720 1721 Args: 1722 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. `virtual_path` values should be URL-encoded if they contain slashes. 1723 input: Request body. 1724 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1725 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. 1726 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1727 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1728 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1729 1730 Returns: 1731 The config in its newly archived state. 1732 """ 1733 return self._http.request( 1734 f"/api/v1/config/{config}/archive", 1735 method="POST", 1736 body=input, 1737 response_type=Config, 1738 )
Archive a config
Soft-deletes a config by marking it as archived. Archived configs are hidden
from list and show endpoints but are not permanently removed; use the
unarchive endpoint to restore one, or the delete endpoint for permanent
removal.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system);
passing an owner selector when addressing by ID returns 422.
Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key.virtual_pathvalues should be URL-encoded if they contain slashes. - input: Request body.
- input.agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. Useful when the viewer has access to multiple orgs. - input.system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - input.team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key.
Returns:
The config in its newly archived state.
def
change_owner( self, config: str, input: ConfigChangeOwnerInput) -> archastro.platform.types.config.Config:
1740 def change_owner(self, config: str, input: ConfigChangeOwnerInput) -> Config: 1741 """ 1742 Transfer ownership of a config 1743 Transfers a config to a new owner (`team`, `user`, `agent`, or `system`). 1744 Exactly one of the new-owner selectors must be provided. The config must be 1745 addressed by its ID (`cfg_...` or UUID); `virtual_path` and `lookup_key` 1746 are not accepted to avoid ambiguity look up the ID first if needed. 1747 For non-system targets the new owner's org is derived automatically from the 1748 target entity; supplying `org` in that case returns 422. For `system:true` 1749 targets, `org` controls the resulting org scope: omit to keep the existing 1750 `org_id`, supply a value to set a specific org, or pass `null`/blank to make 1751 the config app-level (operator viewers only). 1752 Operator viewers (developer credentials or all-powerful viewers) may transfer 1753 to any owner. All other viewers are restricted to owners they can themselves 1754 access (team membership, user identity, agent scope, or `system` with the 1755 appropriate privilege). 1756 Requires app scope. The viewer must have modify rights on the config. 1757 1758 Args: 1759 config: Config ID in id-form: `cfg_...` or a UUID. `lookup_key` and `virtual_path` are not accepted retrieve the config ID first if you only have a path. 1760 input: Request body. 1761 input.agent: New owner: Agent ID (`agt_...`). Mutually exclusive with `team`, `user`, and `system`. 1762 input.org: Only valid when `system:true`. Omit to keep the config's existing `org_id`; supply an org ID (`org_...`) to set a specific org scope; pass blank or `null` to make the config app-level (operator viewers only). Setting `org` for `team`, `user`, or `agent` targets returns 422. 1763 input.system: Set `true` to transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive with `team`, `user`, and `agent`. 1764 input.team: New owner: Team ID (`team_...`). Mutually exclusive with `user`, `agent`, and `system`. 1765 input.user: New owner: User ID (`usr_...`). Mutually exclusive with `team`, `agent`, and `system`. 1766 1767 Returns: 1768 The config reflecting its new ownership. 1769 """ 1770 return self._http.request( 1771 f"/api/v1/config/{config}/change_owner", 1772 method="POST", 1773 body=input, 1774 response_type=Config, 1775 )
Transfer ownership of a config
Transfers a config to a new owner (team, user, agent, or system).
Exactly one of the new-owner selectors must be provided. The config must be
addressed by its ID (cfg_... or UUID); virtual_path and lookup_key
are not accepted to avoid ambiguity look up the ID first if needed.
For non-system targets the new owner's org is derived automatically from the
target entity; supplying org in that case returns 422. For system:true
targets, org controls the resulting org scope: omit to keep the existing
org_id, supply a value to set a specific org, or pass null/blank to make
the config app-level (operator viewers only).
Operator viewers (developer credentials or all-powerful viewers) may transfer
to any owner. All other viewers are restricted to owners they can themselves
access (team membership, user identity, agent scope, or system with the
appropriate privilege).
Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config ID in id-form:
cfg_...or a UUID.lookup_keyandvirtual_pathare not accepted retrieve the config ID first if you only have a path. - input: Request body.
- input.agent: New owner: Agent ID (
agt_...). Mutually exclusive withteam,user, andsystem. - input.org: Only valid when
system:true. Omit to keep the config's existingorg_id; supply an org ID (org_...) to set a specific org scope; pass blank ornullto make the config app-level (operator viewers only). Settingorgforteam,user, oragenttargets returns 422. - input.system: Set
trueto transfer to system ownership (app-level or org-scoped). Requires a privileged viewer. Mutually exclusive withteam,user, andagent. - input.team: New owner: Team ID (
team_...). Mutually exclusive withuser,agent, andsystem. - input.user: New owner: User ID (
usr_...). Mutually exclusive withteam,agent, andsystem.
Returns:
The config reflecting its new ownership.
def
content( self, config: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, system: bool | None = None, org: str | None = None, format: str | None = None, inject_protected_fields: bool | None = None) -> dict[str, str]:
1777 def content( 1778 self, 1779 config: str, 1780 *, 1781 team: str | None = None, 1782 user: str | None = None, 1783 agent: str | None = None, 1784 system: bool | None = None, 1785 org: str | None = None, 1786 format: str | None = None, 1787 inject_protected_fields: bool | None = None, 1788 ) -> dict[str, str]: 1789 """ 1790 Retrieve a config's raw content 1791 Returns the raw byte content of a config's current version. The response 1792 `Content-Type` header reflects the config's stored MIME type unless a 1793 `format` conversion is requested. 1794 Pass `format: "yaml"` or `format: "json"` to convert between YAML and JSON 1795 on the fly. Conversion is only supported between these two formats; requesting 1796 a conversion that is not possible returns 400. 1797 By default, `virtual_path` and other platform-injected protected fields are 1798 embedded in the returned content. Set `inject_protected_fields: false` to 1799 return the stored raw bytes exactly as written. 1800 The config may be addressed by ID (`cfg_...`), `virtual_path`, or 1801 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, exactly one 1802 owner selector (`team`, `user`, `agent`, or `system`) is required. 1803 1804 Args: 1805 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1806 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1807 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1808 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1809 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1810 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1811 format: Output format for content conversion. One of `"yaml"` or `"json"`. Omit to return the content in its stored format. Returns 400 if conversion is not possible. 1812 inject_protected_fields: Whether to inject platform-managed protected fields (such as `virtual_path`) into the returned content. Defaults to `true`. Set to `false` to receive the raw stored bytes. 1813 1814 Returns: 1815 Raw config content in the stored or requested format. 1816 """ 1817 query: dict[str, object] = {} 1818 if team is not None: 1819 query["team"] = team 1820 if user is not None: 1821 query["user"] = user 1822 if agent is not None: 1823 query["agent"] = agent 1824 if system is not None: 1825 query["system"] = system 1826 if org is not None: 1827 query["org"] = org 1828 if format is not None: 1829 query["format"] = format 1830 if inject_protected_fields is not None: 1831 query["inject_protected_fields"] = inject_protected_fields 1832 return self._http.request_raw(f"/api/v1/config/{config}/content", query=query)
Retrieve a config's raw content
Returns the raw byte content of a config's current version. The response
Content-Type header reflects the config's stored MIME type unless a
format conversion is requested.
Pass format: "yaml" or format: "json" to convert between YAML and JSON
on the fly. Conversion is only supported between these two formats; requesting
a conversion that is not possible returns 400.
By default, virtual_path and other platform-injected protected fields are
embedded in the returned content. Set inject_protected_fields: false to
return the stored raw bytes exactly as written.
The config may be addressed by ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, exactly one
owner selector (team, user, agent, or system) is required.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. - format: Output format for content conversion. One of
"yaml"or"json". Omit to return the content in its stored format. Returns 400 if conversion is not possible. - inject_protected_fields: Whether to inject platform-managed protected fields (such as
virtual_path) into the returned content. Defaults totrue. Set tofalseto receive the raw stored bytes.
Returns:
Raw config content in the stored or requested format.
def
unarchive( self, config: str, input: ConfigUnarchiveInput) -> archastro.platform.types.config.Config:
1834 def unarchive(self, config: str, input: ConfigUnarchiveInput) -> Config: 1835 """ 1836 Unarchive a config 1837 Restores a previously archived config, making it visible again in list and 1838 show responses. The config's content and version history are unchanged. 1839 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1840 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1841 supply exactly one owner selector (`team`, `user`, `agent`, or `system`); 1842 passing an owner selector when addressing by ID returns 422. 1843 Requires app scope. The viewer must have modify rights on the config. 1844 1845 Args: 1846 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1847 input: Request body. 1848 input.agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1849 input.org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1850 input.system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1851 input.team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1852 input.user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1853 1854 Returns: 1855 The config in its newly restored (active) state. 1856 """ 1857 return self._http.request( 1858 f"/api/v1/config/{config}/unarchive", 1859 method="POST", 1860 body=input, 1861 response_type=Config, 1862 )
Unarchive a config
Restores a previously archived config, making it visible again in list and
show responses. The config's content and version history are unchanged.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system);
passing an owner selector when addressing by ID returns 422.
Requires app scope. The viewer must have modify rights on the config.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - input: Request body.
- input.agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org. - input.system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - input.team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - input.user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key.
Returns:
The config in its newly restored (active) state.
def
versions( self, config: str, *, team: str | None = None, user: str | None = None, agent: str | None = None, system: bool | None = None, org: str | None = None) -> ConfigVersionsResponse:
1864 def versions( 1865 self, 1866 config: str, 1867 *, 1868 team: str | None = None, 1869 user: str | None = None, 1870 agent: str | None = None, 1871 system: bool | None = None, 1872 org: str | None = None, 1873 ) -> ConfigVersionsResponse: 1874 """ 1875 List a config's version history 1876 Returns all versions of a config in the order they were created, most recent 1877 first. Each version includes its version number, content metadata, and change 1878 description. The raw content bytes for a specific version are not included; 1879 use the content endpoint to fetch them. 1880 The config may be addressed by its ID (`cfg_...`), `virtual_path`, or 1881 `lookup_key`. When addressing by `lookup_key` or `virtual_path`, you must 1882 supply exactly one owner selector (`team`, `user`, `agent`, or `system`). 1883 Both `not_found` and `forbidden` outcomes are surfaced as 404. 1884 Requires app scope. 1885 1886 Args: 1887 config: Config identifier. Accepts a config ID (`cfg_...`), a `virtual_path`, or a `lookup_key`. URL-encode `virtual_path` values that contain slashes. 1888 team: Team ID (`team_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1889 user: User ID (`usr_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1890 agent: Agent ID (`agt_...`) to use as the owner when resolving by `virtual_path` or `lookup_key`. 1891 system: Set `true` to resolve a system-owned config by `virtual_path` or `lookup_key`. Requires a privileged viewer (developer or all-powerful) or an org admin. 1892 org: Organization ID (`org_...`) to narrow the lookup to configs belonging to that org. 1893 1894 Returns: 1895 Successful response 1896 """ 1897 query: dict[str, object] = {} 1898 if team is not None: 1899 query["team"] = team 1900 if user is not None: 1901 query["user"] = user 1902 if agent is not None: 1903 query["agent"] = agent 1904 if system is not None: 1905 query["system"] = system 1906 if org is not None: 1907 query["org"] = org 1908 return self._http.request( 1909 f"/api/v1/config/{config}/versions", 1910 query=query, 1911 response_type=ConfigVersionsResponse, 1912 )
List a config's version history
Returns all versions of a config in the order they were created, most recent
first. Each version includes its version number, content metadata, and change
description. The raw content bytes for a specific version are not included;
use the content endpoint to fetch them.
The config may be addressed by its ID (cfg_...), virtual_path, or
lookup_key. When addressing by lookup_key or virtual_path, you must
supply exactly one owner selector (team, user, agent, or system).
Both not_found and forbidden outcomes are surfaced as 404.
Requires app scope.
Arguments:
- config: Config identifier. Accepts a config ID (
cfg_...), avirtual_path, or alookup_key. URL-encodevirtual_pathvalues that contain slashes. - team: Team ID (
team_...) to use as the owner when resolving byvirtual_pathorlookup_key. - user: User ID (
usr_...) to use as the owner when resolving byvirtual_pathorlookup_key. - agent: Agent ID (
agt_...) to use as the owner when resolving byvirtual_pathorlookup_key. - system: Set
trueto resolve a system-owned config byvirtual_pathorlookup_key. Requires a privileged viewer (developer or all-powerful) or an org admin. - org: Organization ID (
org_...) to narrow the lookup to configs belonging to that org.
Returns:
Successful response