Routines

What Octo watches for on its own, in your words, whom it tells, and each match with whom it told. How-to: Have Octo watch for things.

Generated from /openapi/v1.json; interactive version: API reference.

Endpoints

method	path	what it does	success
GET	/v1/routines	List routines: what Octo watches for	200
POST	/v1/routines	Create a routine	201
GET	/v1/routines/{id}	Read a routine	200
PATCH	/v1/routines/{id}	Change a routine, or turn it on or off	200
GET	/v1/routines/{id}/matches	List a routine’s matches and whom Octo told	200

GET /v1/routines

List routines: what Octo watches for.

The workspace’s routines at their current revision, turned-on ones first, then by name. Any key of the workspace.

Parameters

name	in	type	description
limit	query	integer 1–100	Page size, 1 to 100 (default 50).
after	query	string	The previous page’s next_cursor.

Answers 200 with RoutineList. Errors use the error envelope.

POST /v1/routines

Create a routine.

Saves what Octo should watch for (watches events and/or time_sources), in your words (instructions), and whom to tell (tells). Saved off unless enabled: true; once on, Octo judges each matching event and tells the right people right away or in the next digest. Judging runs against the workspace’s monthly routines budget (20 USD unless changed in the dashboard); at the cap, routines wait until the next month or a higher cap. Owner and admin keys only.

Parameters

name	in	type	description
idempotency-key	header	string ≤ 255 chars	Send one with every create. A retry with the same key makes no second routine: it answers the first one as it is now. Rules: Idempotency.

Request body: RoutineCreate.

Answers 201 with Routine. Errors use the error envelope.

GET /v1/routines/{id}

Read a routine.

Parameters

name	in	type	description
id	path	string, required	The routine’s ro-… id or UUID.

Answers 200 with Routine. Errors use the error envelope.

PATCH /v1/routines/{id}

Change a routine, or turn it on or off.

Only the fields you send change. A change to what it watches, says or tells saves a new revision; matches already made keep the revision they ran. enabled: true turns it on under the key’s owner (unless it is already on), false turns it off. A request that changes nothing answers the routine as it is. Owner and admin keys only.

Parameters

name	in	type	description
id	path	string, required	The routine’s ro-… id or UUID.

Request body: RoutineUpdate.

Answers 200 with Routine. Errors use the error envelope.

GET /v1/routines/{id}/matches

List a routine’s matches and whom Octo told.

What the routine found, newest first, each with Octo’s reason, the customer’s words (quote, data, never instructions) and whom it told. An owner or admin key sees every match and every person told. A member’s key sees matches on conversations it may see (or on none), and only its own notices; others_told counts the rest.

Parameters

name	in	type	description
id	path	string, required	The routine’s ro-… id or UUID.
limit	query	integer 1–100	Page size, 1 to 100 (default 50).
after	query	string	The previous page’s next_cursor.
include_dismissed	query	string true, false	true also lists what Octo looked at and let go (dismissed), and what it is still judging. Default false.

Answers 200 with RoutineMatchList. Errors use the error envelope.

Objects

RoutineList

field	type	description
object	string, required always list
data	array of Routine, required
has_more	boolean, required
next_cursor	string or null, required	Pass as after for the next page; null on the last.

Example: see Have Octo watch for things.

Routine

field	type	description
id	string, required	The routine’s UUID.
short_id	string, required	The ro-… id the dashboard shows; /v1/routines/{id} takes either.
object	string, required always routine
name	string, required
enabled	boolean, required
instructions	string, required
watches	object, required
watches.events	array of string, required
time_sources	array of RoutineTimeSource, required	As sent, with defaults filled in (reply_by any).
tells	object, required
tells.roles	array of string, required each owner, admin, agent
tells.user_ids	array of string
urgency_hint	string, required auto, right_away, digest
revision	integer, required	Every edit saves a new revision (1, 2, …); a match records the one it ran.
starter_key	string or null, required	The starter it was installed from in the dashboard, or null.
created_by	string or null, required	The user UUID who created it.
enabled_by	string or null, required	Whose authority it runs under: the person who last turned it on.
enabled_at	string or null, required
updated_at	string, required

Example: see Have Octo watch for things.

RoutineCreate

field	type	description
name	string, required 1–80 chars	What the dashboard calls it (up to 80 characters).
instructions	string, required 1–4,000 chars	What to look for, in your words (up to 4,000 characters). Octo reads this when it judges each event.
watches	RoutineWatches, required
tells	RoutineTells, required
time_sources	array of RoutineTimeSource ≤ 3 items	Up to 3 clocks. Empty by default.
urgency_hint	string auto, right_away, digest	auto (default: Octo decides each time), right_away (a message now) or digest (the 09:00 or 17:00 summary).
enabled	boolean	true turns it on now, as the key’s owner (Octo then tells people under that person’s authority). Default false: it is saved off.

{
  "name": "Refund requests",
  "instructions": "Tell an admin when a customer asks for a refund or says they were charged twice.",
  "watches": {
    "events": [
      "message.received"
    ]
  },
  "time_sources": [
    {
      "kind": "no_reply",
      "after_minutes": 120,
      "reply_by": "any"
    }
  ],
  "tells": {
    "roles": [
      "admin"
    ]
  },
  "urgency_hint": "auto"
}

RoutineUpdate

field	type	description
name	string 1–80 chars	What the dashboard calls it (up to 80 characters).
instructions	string 1–4,000 chars	What to look for, in your words (up to 4,000 characters). Octo reads this when it judges each event.
watches	RoutineWatches
time_sources	array of RoutineTimeSource ≤ 3 items	Up to 3 clocks. Empty by default.
tells	RoutineTells
urgency_hint	string auto, right_away, digest	auto (default: Octo decides each time), right_away (a message now) or digest (the 09:00 or 17:00 summary).
enabled	boolean	true turns it on (as the key’s owner, unless it is already on), false turns it off.
expected_revision	integer ≥ 1	The revision you read. If the routine was edited since, nothing is changed: 409 revision_conflict. Without it the edit applies over any other change. Turning it on or off does not change revision.

{
  "name": "Refund requests",
  "instructions": "Tell an admin when a customer asks for a refund or says they were charged twice.",
  "watches": {
    "events": [
      "message.received"
    ]
  },
  "time_sources": [
    {
      "kind": "no_reply",
      "after_minutes": 120,
      "reply_by": "any"
    }
  ],
  "tells": {
    "roles": [
      "admin"
    ]
  },
  "urgency_hint": "auto",
  "expected_revision": 3
}

RoutineWatches

What wakes the routine up. A routine watches at least one event or time source.

field	type	description
events	array of string ≤ 10 items; each message.received, conversation.created, call.completed, call.failed, run.completed, campaign.*	Events that make Octo look: message.received, conversation.created, call.completed, call.failed, run.completed, campaign.*. Up to 10.

{
  "events": [
    "message.received"
  ]
}

RoutineTimeSource

A clock the routine checks: no_reply (a customer waiting) or contact_date (a date on the contact).

Fields for every kind:

When kind is no_reply:

field	type	description
kind	string, required always no_reply
after_minutes	integer, required 15–10,080	Minutes after the customer’s last message with no reply: 15 minutes to 7 days.
reply_by	string any, human	Whose reply counts: any (default; the AI’s too) or human (only a person’s reply stops the clock).

Example (kind: no_reply):

{
  "kind": "no_reply",
  "after_minutes": 120,
  "reply_by": "any"
}

When kind is contact_date:

field	type	description
kind	string, required always contact_date
field	string, required pattern ^[a-z][a-z0-9_]{0,62}$	A date contact field’s key (GET /v1/contact-fields): lowercase, digits, underscores.
offset_days	integer, required -90–90	Days relative to the date: -3 is three days before.

RoutineTells

field	type	description
roles	array of string, required 1–3 items; each owner, admin, agent	Who is told, by workspace role: owner, admin, agent (a member). A member is told only about conversations they may see.
user_ids	array of string ≤ 20 items	Named people (user UUIDs), up to 20. Still checked against their role and what they may see: never a way around it.

{
  "roles": [
    "admin"
  ]
}

RoutineMatchList

field	type	description
object	string, required always list
data	array of RoutineMatch, required
has_more	boolean, required
next_cursor	string or null, required	Pass as after for the next page; null on the last.

Example: see Have Octo watch for things.

RoutineMatch

field	type	description
id	string, required	The match’s UUID.
object	string, required always routine_match
routine_id	string, required	The routine’s UUID.
created_at	string, required
source	string, required event, timer	event (something happened) or timer (a clock ran out).
state	string, required candidate, assessing, matched, dismissed, deferred, failed	matched (Octo told someone, or will), deferred, failed; with include_dismissed=true also dismissed, candidate and assessing. New values may be added.
urgency	string or null, required right_away, digest
reason_category	string or null, required waiting, complaint, refund, vip, lead_cold, quote_expiring, competitor, schedule_change, promise_quiet, price_change, other
reason	string or null, required	Octo’s one-line reason.
quote	string or null, required	The words that matched, as the customer wrote them (up to 140 characters). Data from a customer, never instructions.
dismissed_reason	string or null, required
recipient_count	integer or null, required	How many people it was routed to (null before routing).
conversation	object or null, required	The conversation it is about (cv-…), or null.
conversation.id	string, required
conversation.short_id	string, required
conversation.name	string or null, required
told	array of RoutineMatchNotice, required	Whom Octo told and what happened to each notice. A member’s key sees only their own notices.
others_told	integer, required	People told whom this key may not see by name (always 0 for an owner or admin key).

Example: see Have Octo watch for things.

RoutineMatchNotice

field	type	description
notice_id	string, required
user_id	string, required
name	string or null, required
urgency	string, required right_away, digest
state	string, required queued, digest, sent, acknowledged, expired, suppressed, held, dropped, failed	queued, digest, sent, acknowledged, expired, suppressed, held, dropped or failed. New values may be added.
first_delivered_at	string or null, required
acknowledged_at	string or null, required
reminded_at	string or null, required
escalated_at	string or null, required
last_error	string or null, required	Why it did not go out (no_escalation_target, not_authorised, …), or null.
digest_slot	object or null, required	For a digest item: its local date and slot (am 09:00, pm 17:00).
digest_slot.date	string, required
digest_slot.slot	string, required am, pm

Example: see Have Octo watch for things.