@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.

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 of the given schema type that are 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.

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 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.

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), or both — but the same field name must not appear in both, which returns 422. Returns 404 if the object does not exist or has been deleted.

Successful response