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