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

Activate a routine

Sets the routine's status to "active", enabling it to process events or run on its configured schedule. Only routines that have a workflow config attached can be activated; attempting to activate a routine with no config returns 422.

Scheduled routines must be configured to run no more frequently than once per hour. Activation fails with 422 if the cron schedule is more frequent than that limit. Requires app scope.

The updated routine with status set to "active".

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

Delete a routine

Permanently deletes the specified routine. This action is irreversible — the routine and its configuration are removed immediately. Any in-flight event processing initiated by this routine before deletion may still complete.

Requires app scope. Returns 204 No Content on success.

Empty response on successful deletion (HTTP 204 No Content).

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

Retrieve a routine

Returns the full routine record for the given routine ID. Use this endpoint to inspect a routine's current configuration, handler type, event config, schedule, and lifecycle status.

Requires app scope. Returns 404 if the routine does not exist or is not accessible to the caller.

The requested routine.

@spec invoke(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentRoutinesRoutineInvoke.Input.t()
) ::
  {:ok, ArchAstro.Types.AgentRoutineRun.t()}
  | {:error, ArchAstro.Error.reason()}

Invoke a routine

Triggers an on-demand invocation of the specified routine, dispatching an asynchronous agent run and returning a run record immediately. The routine must be active and must have event_type set to "agentroutine.invoked".

The routine's preset_config.session_mode determines session behavior: each call may create a new session ("stateless") or reuse an existing one ("session"). When session_scope is "per_user", the user param is required for S2S and developer callers; authenticated client callers always use their own identity. When session_scope is "per_key", session_key is required.

Supply idempotency_key to safely retry invocations — if a completed run already exists for that key a 409 Conflict is returned rather than creating a duplicate run. Entitlement for LLM calls is checked at request time; customers on plans that do not include this feature receive 402.

Use delivery to propagate the final textual result into a conversation. {"type":"reply","message":"msg_..."} preserves the message's external origin (for example Slack), while {"type":"thread","thread":"thr_..."} posts without a reply anchor. Chain routines deliver only their final result.

For workflow-graph routines that dispatch distributed work, pass optional participants (map of symbolic refs to agent ids, e.g. {"investigator":"agi_..."}) as a top-level field next to free-form invoke inputs — same shape as automation invoke. Free-form fields stay on event_payload; participants are stored in the run's top-level participants field and exposed through workflow system context so embed_agent nodes can resolve assignees.

The agent routine run created by this invocation.

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

List routines

Returns all routines within the authenticated app scope. Optionally filter by agent or event type. When agent is omitted, all routines accessible to the caller are returned regardless of which agent they belong to.

If agent is provided but does not exist or is not accessible, the endpoint returns 404 rather than an empty list. Results are not paginated; all matching routines are returned in a single response. Requires app scope.

Object containing a data array of matching routines.

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

Pause a routine

Sets the routine's status to "paused", suspending event processing and scheduled execution without deleting the routine or its configuration. A paused routine can be resumed at any time by calling the activate endpoint.

Requires app scope.

The updated routine with status set to "paused".

@spec presets(ArchAstro.Client.t()) ::
  {:ok, [ArchAstro.Types.RoutinePreset.t()]}
  | {:error, ArchAstro.Error.reason()}

List routine presets

Returns all registered routine presets available to the authenticated app, including each preset's name, display metadata, and accepted configuration schema. Use this endpoint to discover which presets can be referenced when creating or updating a routine with handler_type: "preset".

The list reflects presets registered at server start time and does not change at runtime. Requires app scope.

Array of available routine preset objects.

@spec runs(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.GetApiV1AgentRoutinesRoutineRuns.Params.t()
) ::
  {:ok, ArchAstro.Types.AgentRoutineRunListResponse.t()}
  | {:error, ArchAstro.Error.reason()}

List runs for a routine

Returns a cursor-paginated list of runs for the specified routine, ordered from most recent to oldest by default. Use before_cursor and after_cursor to page through results in either direction.

You can filter runs by status to monitor a specific lifecycle phase. The authenticated principal must have access to the routine's parent app. When your API key is scoped to an app, only runs belonging to that app are returned.

Paginated list of routine runs.

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

Update a routine

Updates one or more fields of the specified routine. Only the fields you include are changed; omitted fields retain their current values. To change the execution model, supply a new handler_type along with its required handler body field (config, script, or preset_name).

When template is supplied, the routine's configuration is re-resolved from the template before applying any additional field overrides. The routine's status, lookup_key, and agent attachment are always preserved regardless of template content. Updating steps replaces the entire step list — send the full desired list, not a partial diff. Requires app scope.

The updated routine.