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

Create a custom object

Creates a new custom object of the given schema type and returns the persisted object. The caller must be authenticated and authorized to create objects of the specified type.

Identify the schema with type (preferred), or the legacy aliases schema_key (lookup key) / config (config ID). Exactly one identifier is required; when more than one is supplied, type wins over schema_key, which wins over config.

Owner resolution follows a priority order: if team is supplied the object is team-owned; if user is supplied it is owned by that user; if agent is supplied it is agent-owned; otherwise the object is owned by the authenticated user. Pass system: true explicitly to force system ownership — this requires elevated API credentials and returns 403 if the caller lacks permission.

If the schema declares a row_key (and optionally a sort_key), you may pass upsert: true to update an existing object at that key instead of receiving a 409 Conflict. The response status is 200 on an update and 201 on a new create.

The created (or upserted) custom object.

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

Delete a custom object

Permanently deletes the custom object identified by object. The caller must be authenticated and have permission to delete the object.

On success, returns a confirmation payload containing the deleted object's ID so callers can confirm the deletion without a follow-up fetch. Attempting to delete an object that does not exist or has already been deleted returns 404.

Successful response

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

Retrieve a custom object

Returns a single custom object identified by its ID. The authenticated viewer must have visibility access to the object.

Returns 404 if the object does not exist, has been deleted, or is not visible to the viewer.

The requested custom object.

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

List custom objects

Returns a paginated list of custom objects visible to the authenticated viewer, ordered by creation time descending. Results span all ownership types (team-owned, user-owned, agent-owned, and system-owned) that the viewer has access to.

Filter by schema type with type (preferred) or the legacy alias schema_key. Use the row_key param to perform an exact-match partition lookup. You may additionally supply sort_key to narrow within that partition — sort_key requires row_key and the request returns 400 if sort_key is provided alone. Owner filters (team, user, agent, org) are additive: each accepts an array of IDs (or a single ID, which is wrapped) and returns objects matching any of the supplied values.

When query is supplied, results are ranked by full-text relevance (descending ts_rank) rather than creation time. The legacy search param performs a case-insensitive substring match and is retained for developer-namespace clients.

Paginated list of custom objects matching the supplied filters.

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

Update a custom object

Updates the fields of an existing custom object and returns the updated object along with its new version number. The authenticated viewer must have permission to modify the object.

You may supply fields (a full or partial key-value map to merge into the object), field_ops (granular array operations per field), acl, or any compatible combination. The same field name must not appear in both fields and field_ops, which returns 422. Returns 404 if the object does not exist or has been deleted.

Successful response