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