Tool reference

Reads the live value bound to a key — or up to 25 keys in one call — nothing is cached as truth.

Inputs, results and an example

Inputs

Field	Type	Description
key	string	One bound key to recall, e.g. customer.acme.address.
keys	string[], instead of key	1 to 25 bound keys, e.g. ["customer.acme.address", "order.42.status"]. Duplicates are read once.

Give key or keys, never both.

Comes back

• resolved — the current value, as of the moment you asked.
• ambiguous — every live candidate that disagrees, never a pick.
• unavailable — nothing is bound for that key, or the source couldn't be reached.

With keys (until 2026-09-26, the separate recall_live_facts): { results: [{ key, ...the same shape }], as_of } — one entry per deduped key, in the order you asked, each answered independently, so one unresolved key never changes another's answer and one bad key never fails the batch.

Example

{ "status": "ambiguous", "candidates": [
  { "value": "12 Main St, Springfield", "confidence": 0.5 },
  { "value": "88 Industrial Ave, Springfield", "confidence": 0.5 }
], "guidance": "Two or more live sources disagree. Do not choose one or state any as the answer — this waits for a person." }

Ask whether an action of this kind is authorized. It is authorized only when the fact is settled; otherwise it waits for a person, and it never guesses. An unregistered kind is refused. Ogen never performs the action itself — your own system does that, once this says yes.

Inputs, results and an example

Inputs

Field	Type	Description
kind	string	An action kind, e.g. one registered with register_action, or a free-tier demo kind.
args	object, optional	The arguments you will run the action with. Ogen keeps only their fingerprint, for the release ticket a confirmation issues; they never choose the fact the action depends on.
principal	{ email }, optional	The person the agent is acting FOR — required when the kind's approver is the reserved word "principal", refused on any other kind. Nothing but the address. See The person the agent acts for.

Comes back

{ committed, disposition, action_id, reason, guidance, confirm_url, notified, approver, webhook, mode }. A result that holds also carries assist, elicited ("accepted" | "declined" | "cancelled" | "unavailable" | "skipped" — whether your client was asked for answers to Assist's questions, see Ogen Assist) and answers_count (how many were attached to the hold; never the answers). committed is true only when disposition is "ran" — every other disposition also carries a reason from a small closed set, so you can branch on it instead of parsing guidance. mode ("gate" | "observe") is on every result, so you can always tell which mode answered without a separate call. What each combination means, and what to do next:

Example

{
  "committed": false,
  "disposition": "held",
  "action_id": "act_9f2c1a",
  "reason": "cost_needs_person",
  "guidance": "The action was HELD for a named human's approval and did NOT fire. Do not perform it yourself.",
  "confirm_url": "https://ogenhq.com/confirm/c_7b3e",
  "notified": true,
  "approver": "Dana",
  "webhook": "sent",
  "mode": "gate"
}

Tell Ogen which fact an action kind depends on, and how costly that action is to undo. Actions that are costly to undo wait for a person — and a kind that waits for a person has to name one.

Inputs, results and an example

A kind that needs a person names one. Any cost other than read must carry an approver the tenant already registered with register_approver; without one the call is refused and says so. Kinds registered before this rule keep working unchanged.

Requires an owner key or a signed-in person. A plain operator key is refused with "this key is an operator; ask an owner, or sign in" — see Roles.

The person a hold is waiting on can be changed while the hold is open. Re-register the kind with a different registered approver and every hold still waiting on it is handed to that person instead: they get the link, and any sign-in link the previous approver was holding stops working. cost and key can't change while a hold is open.

Inputs

Field	Type	Description
kind	string	The action kind commit_gated_action will be called with.
key	string	The bound key this kind depends on.
cost	read | reversible | expensive	How costly this kind of action is to undo. The costlier it is to undo, the more a person is involved before it happens.
approver	string	The name of the person who confirms a hold on this kind (see register_approver) — or the reserved word "principal", which waits for whoever commit_gated_action's own ask names instead (see The person the agent acts for). Required for any cost other than read, and for decide_with "passkey_only" (which a principal-gated kind can never use — a principal has no passkey). Omit it when re-registering and whoever is already named stays named; null clears it, which only a read kind with decide_with "token_or_passkey" may do.
decide_with	token_or_passkey | passkey_only, optional	Which door may decide this kind's holds — a mailed one-time token or a passkey (the default), or a passkey only. Omit on a re-registration and whatever is already set stays set.
hold_ttl_hours	integer 1–168, optional	How long a hold on this kind waits for a person. Default 24. Each hold's deadline is fixed when it's created; changing this never moves a hold already waiting. A longer window is a longer time for the fact to move — and the decision still goes by the fact as it stands when it runs.
hold_ttl_skip_weekends	boolean, optional	Count only working days, in your timezone (settings, action "contact"), toward hold_ttl_hours. With the default Saturday–Sunday weekend, a payment held Friday 18:00 with 24 hours lapses Monday 18:00 instead of Saturday 18:00; the same action's weekend can make it Friday and Saturday instead. The reminder and the hand-over fall at 80% and 50% of the same working time, so a weekend never pulls them forward. Default false. Refused until the account has a timezone, and when that timezone is one Ogen doesn't know.
fallback_approver	string, optional	A second registered person who is handed a hold on this kind once half its life has passed with no decision (What happens to a hold). Needs an approver, must be someone else, and must already be registered. Omit on a re-registration and whoever is set stays set; null clears it.
release_when	object, optional	Release this kind without a person when its OWN bound fact resolves and satisfies the rule — exactly one of { fact_equals: "<string>" } or { fact_at_least: "<argument name>" } (see Release without a person — your own fact). Only on a cost expensive kind; never with decide_with passkey_only. Owner key only. Omit on a re-registration and whatever is set stays set; null clears it.

Comes back

A confirmation that the kind is registered, with the key, cost and door it now maps to.

Example

Registered "email-globex" -> "customer.globex.address" (cost: reversible, decide_with: token_or_passkey). commit_gated_action will honor it from now on.

Tell Ogen where to reach a person by name, so a held action can be sent to them.

Inputs, results and an example

Requires an owner key or a signed-in person. A plain operator key is refused with "this key is an operator; ask an owner, or sign in" — see Roles.

Inputs

Field	Type	Description
name	string	The approver's name — must match a register_action approver value exactly.
email	string (email)	The approver's email address.
replace	boolean, optional	true to move an existing name to a different email. The old address is told, and any passkeys set up under this name stop working.
revoke_passkeys	boolean, optional	true to turn off every passkey this approver set up — a lost device, a person leaving. They can set up a new one from their next emailed link.

Comes back

A confirmation that this name now resolves to that address for held-action email — plus passkeys_revoked, a count, whenever passkeys were turned off.

Example

{ "registered": true }

This tenant's held actions — open, decided, or both — newest first, up to 100 at a time. The same fields explain_hold returns for one hold, for every hold at once. Also reachable as GET /v1/holds with your bearer key, for your own tooling.

Inputs, results and an example

Inputs

Field	Type	Description
status	"open" | "decided", optional	Omit for both.
limit	number, optional	Default and cap 100.
include	"expired", optional	Also list holds that expired with nobody deciding. Left out by default, so “open” means still waiting. GET /v1/holds?include=expired does the same.

Comes back

{ holds: [ …one entry per hold, same shape as explain_hold… ] }

Everything about ONE held action, for a person or their assistant to look at: what it waited on, what each source said, and a fix template a person can complete. Ogen never chooses.

Inputs, results and an example

Inputs

Field	Type	Description
action_id	string	The action_id returned by commit_gated_action.

Comes back

The hold's kind, key, current live state (a resolved value, or every candidate with the source label it came from — never a credential, and unlike recall_live_fact no confidence number), held_since, the named approver if any, decide_with (which door may decide this kind — "token_or_passkey" or "passkey_only"), its confirm_url, and a fix_proposal: { tool: "teach_fix", input: { key, raw, canonical: null, taught_by: null } }. canonical and taught_by are always null — a person fills them in. A decided or expired hold says so, and adds decided_via — "token" (the mailed sign-in link), "passkey", or "name" (a typed name, no routable approver) — never the credential id.

Example

{
  "found": true,
  "status": "pending",
  "kind": "send-refund",
  "key": "order.42.status",
  "held_since": "2026-09-05T01:02:03.000Z",
  "approver": "none — anyone with the link can decide",
  "decide_with": "token_or_passkey",
  "confirm_url": "https://ogenhq.com/confirm/…",
  "fact": { "status": "ambiguous", "candidates": [
    { "value": "shipped", "source_label": "orders.example.com" },
    { "value": "returned", "source_label": "orders.example.com" }
  ] },
  "fix_proposal": {
    "tool": "teach_fix",
    "input": { "key": "order.42.status", "raw": null, "canonical": null, "taught_by": null },
    "note": "A person fills in canonical and taught_by. Ogen does not pick."
  }
}

Record a person's correction, so nobody is asked the same thing twice.

Inputs, results and an example

Inputs

Field	Type	Description
key	string	The bound key this fix applies to.
raw	string	The raw value that was wrong.
canonical	string	What it actually means.
taught_by	string	The named person recording this fix — required.

Comes back

The rule that was recorded, with a rule_id you can later hand to reverse (action "restore").

Example

{ "recorded": true, "rule_id": "a1b2c3d4e5f6a7b8" }

Return your stored read fingerprints for offline verification against your own secret.

Inputs, results and an example

Inputs

Field	Type	Description
since	string (ISO timestamp), optional	Only rows at or after this time.

Comes back

Up to 1,000 rows: key, when, its status, and a fingerprint — never a plaintext value.

Example

{ "rows": [
  { "key": "customer.acme.address", "at": "2026-09-01T10:03:00Z", "state": "ambiguous", "fingerprint": "9f2c1a4e..." }
] }

Bind a key to a live, read-only source: a plain JSON endpoint, or one of the named source kinds. Every recall reads it fresh — nothing is cached as truth.

Inputs, results and an example

Inputs

Field	Type	Description
key	string	The key to bind.
url	string (https URL), optional	For a plain JSON endpoint. Omit when using source.
headers	object, optional	Plain-endpoint only — sent exactly as given on every read. Stored encrypted at rest.
source	object, optional	Instead of a plain endpoint — a named kind (postgrest, airtable, gsheets, hubspot, mcp) plus its own fields. See Sources. A named connection (connections) goes in source.connection.
alongside	boolean, optional	Bind a second (up to four) live source to this key instead of replacing the one it already has — see Sources. Omit it (the default) and this call still replaces the key's one source, removing any other source already bound alongside it.

Comes back

{ bound: true, key, kind, label } — label is a safe, non-secret identifier (a host, a base id, a sheet id, an object name), never a credential. With alongside: true, also { slot, systems: [...], note } — every system now bound to this key, and a line saying the fact will wait whenever they disagree.

Example

{ "bound": true, "key": "order.99.status", "kind": "http", "label": "example.com" }

See what a bound source exposes before you name a key against it. Reads that source live, once, and hands back the field names it found and their types — string, number, boolean, object, array — never the underlying values. A nested JSON source is walked into dotted paths (billing_address.street); a table-style source reports the configured column and how many records it saw. Up to ten ready-to-use key names are proposed from what it found. The same result is on your tenant page (a "Fields" button on every bound source) and at GET /v1/sources/<key>/fields.

Inputs, results and an example

Inputs

Field	Type	Description
key	string	A key already bound with bind_source, or one of the demo keys.

Comes back

{ key, kind, sample_count, fields: [{ path, type }], suggested_keys: [...] } — or the same unavailable shape recall_live_fact uses. A key bound to more than one system (Sources, alongside: true) comes back as { key, systems: [{ system, kind, fields, ... }, ...] } instead — one entry per system, so one system being unreachable never hides what another exposes.

Store a credential set once, under a name, for salesforce/netsuite/hubspot/airtable/postgrest/postgres/priority, so bind_source's source.connection names it instead of repeating it. Never echoes a credential back.

Actions, inputs and results

Actions

A field that belongs to another action is refused, naming it. A plain operator key is refused on "set" and "remove" with "this key is an operator; ask an owner, or sign in" — a standing credential changes what every future bind through it reads. See Roles.

Example

{ "action": "set", "name": "sfdc-prod", "kind": "salesforce",
  "instance_url": "https://acme.my.salesforce.com", "client_id": "…", "client_secret": "…" }
→ { "connection": "sfdc-prod", "kind": "salesforce", "label": "acme.my.salesforce.com" }

This tenant's standing settings: gate or observe mode, where Ogen reaches you, evidence recording, Ogen Assist, and the public discovery door. One action per call.

Actions, inputs and results

Actions

A field that belongs to another action is refused, naming it. Every action but "evidence" changes what every future act does, so a plain operator key is refused with "this key is an operator; ask an owner, or sign in". See Roles.

Example

{ "action": "mode", "mode": "observe", "acknowledge": true, "confirm": "nothing will be held" }
→ { "mode": "observe" }

A signed HTTP POST whenever an action is held or escalated (or, in observe mode, when it would have been). One URL per tenant.

Actions, inputs and results

Actions

A plain operator key is refused with "this key is an operator; ask an owner, or sign in" — see Roles.

Record that an action was reversed, so what went wrong is not repeated — or put a correction that was set aside back into force. A named person either way.

Actions, inputs and results

Actions

Tell Ogen whether a confirmed action ran, with the release ticket its confirmation issued. For an agent that runs the action itself; a system without an Ogen key sends the same body to POST /v1/receipts. Ogen records it; it never runs the action.

Inputs, results and an example

Inputs

Field	Type	Description
ticket	string	The release_ticket.
outcome	"ran" | "failed"	Whether your system ran the action.
reference	string, optional	Your system's own id for what it did: 1 to 120 letters, digits, or _ . : - (like re_3NqX). Anything else is refused.
error	string, optional	Why it did not run. Checked, never stored.

Comes back

{ recorded: true, hold_id, action_id, kind, outcome, reference? }, or { recorded: false, reason, guidance }. Each ticket reports once.

Certify a packet of documents against what was read out of them. Checks whether each reading actually says what it claims, and whether documents naming the same field agree. Optionally checks a reading against a supplied record too.

Inputs, results and an example

Inputs

Field	Type	Description
documents	array of { id, kind, text }	Every document in the packet, verbatim.
readings	array of { document_id, field, value, span }	What was read out of the documents — span is the character offset the value was claimed to sit at.
records	array of { entity, values }, optional	External values on record for a field, to check a lone reading against.

Comes back

Per field: whether it is certified, refuted, or unproven, which documents state it, and — when documents disagree — what each one said. release is true only when every field is certified.

{ "release": true, "fields": [
  { "field": "total", "state": "certified", "documents": ["invoice", "po"], "note": "..." }
], "holds": [] }

A short report of what Ogen did for you over a trailing window: what your agent asked, what it was able to act on, what waited for a person, and what a person decided. Every count is from calls already made — nothing here runs on a timer.

Inputs, results and an example

Inputs

Field	Type	Description
days	integer, optional, ≤ 90	Window size in days. Default 7.

Comes back

The same numbers as the public proof page:

• Two signals, read-only, never a release. decided_within_10s_7d is { fast, total } — of the holds decided in the trailing 7 days, how many were decided within 10 seconds of being created (a tell for an approver mailbox forwarded straight to a bot). confirmed_unchanged_streaks is a list of { kind, streak } — action kinds whose last 10 or more decisions were all CONFIRM with no fix ever taught for the key, a nudge to teach_fix the fix once or narrow the kind.

Example

{ "tenant": "t_1a2b3c", "window_days": 7,
  "reads": { "resolved": 41, "ambiguous": 6, "unavailable": 2 },
  "holds": 5, "staleness_caught": 3, "set_aside": 0, "later_released": 1,
  "would_have_acted_on_stale": 11,
  "decided_within_10s_7d": { "fast": 3, "total": 5 },
  "confirmed_unchanged_streaks": [{ "kind": "send-refund", "streak": 12 }] }

Paste a log of your agent's past reads and actions and see how many times it would have acted on stale or uncertain data. Nothing here is stored.

Inputs, results and an example

Inputs

Field	Type	Description
events	array, up to 2,000	Each event: at (ISO timestamp), kind (read | act), plus optional key, value, candidates, acted, later_corrected.

Comes back

{ acted_on_uncertain, stale_reads, repeated_corrections, headline }:

• acted_on_uncertain — times your agent acted while the fact was still disputed.
• stale_reads — reads that were already out of date.
• repeated_corrections — the same fact fixed more than once.
• headline — one sentence: how many times, total, your agent would have acted on stale or uncertain data in this log.

Example

{ "acted_on_uncertain": 2, "stale_reads": 1, "repeated_corrections": 0,
  "headline": "Your agent would have acted on stale or uncertain data 3 times in this log." }