@spec archive(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1ConfigConfigArchive.Input.t()
) :: {:ok, ArchAstro.Types.Config.t()} | {:error, ArchAstro.Error.reason()}

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.

The config in its newly archived state.

@spec change_owner(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1ConfigConfigChangeOwner.Input.t()
) :: {:ok, ArchAstro.Types.Config.t()} | {:error, ArchAstro.Error.reason()}

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.

The config reflecting its new ownership.

@spec content(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1ConfigConfigContent.Params.t()
) :: {:ok, Req.Response.t()} | {:error, ArchAstro.Error.reason()}

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.

Raw config content in the stored or requested format.

@spec create(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1Config.Input.t()
) ::
  {:ok, ArchAstro.Types.Config.t()} | {:error, ArchAstro.Error.reason()}

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.

The newly created config, including its first version.

@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

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.

Empty body. HTTP 204 indicates the config and all its versions were permanently deleted.

@spec encrypt_secret(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1ConfigEncryptSecret.Input.t()
) ::
  {:ok, ArchAstro.Types.Operations.PostApiV1ConfigEncryptSecret.Response.t()}
  | {:error, ArchAstro.Error.reason()}

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.

Successful response

@spec facets(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.GetApiV1ConfigFacets.Params.t()
) ::
  {:ok, ArchAstro.Types.ConfigFacets.t()} | {:error, ArchAstro.Error.reason()}

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.

Distinct config kinds and virtual_path prefixes with per-value counts.

@spec get(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1ConfigConfig.Params.t()
) :: {:ok, ArchAstro.Types.Config.t()} | {:error, ArchAstro.Error.reason()}

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.

The requested config object.

@spec list(ArchAstro.Client.t(), ArchAstro.Types.Operations.GetApiV1Config.Params.t()) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1Config.Response.t()}
  | {:error, ArchAstro.Error.reason()}

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.

Successful response

@spec unarchive(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1ConfigConfigUnarchive.Input.t()
) :: {:ok, ArchAstro.Types.Config.t()} | {:error, ArchAstro.Error.reason()}

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.

The config in its newly restored (active) state.

@spec update(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PatchApiV1ConfigConfig.Input.t()
) :: {:ok, ArchAstro.Types.Config.t()} | {:error, ArchAstro.Error.reason()}

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

409. This prevents overwriting concurrent edits.

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. The viewer must have modify rights on the config.

The config reflecting the applied update.

@spec validate(
  ArchAstro.Client.t(),
  ArchAstro.Types.Operations.PostApiV1ConfigValidate.Input.t()
) ::
  {:ok, ArchAstro.Types.ValidationResult.t()}
  | {:error, ArchAstro.Error.reason()}

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.

Validation outcome. Always HTTP 200; check the valid field to determine success. Includes errors when valid is false.

@spec versions(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1ConfigConfigVersions.Params.t()
) ::
  {:ok, ArchAstro.Types.Operations.GetApiV1ConfigConfigVersions.Response.t()}
  | {:error, ArchAstro.Error.reason()}

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.

Successful response