Recuriant

Documentation

Build a workflow you can execute and inspect.

For teams with app access. Follow an event into an agent task, inspect its execution and define the event that confirms the outcome. API and policy references are included below.

  1. 1

    Start in Workflows.

    Once your access is set up, open Workflows. A workspace without workflows offers a starter you can install and run from the app.

    This quickstart uses the hosted app.

    Pre-register
  2. 2

    Define the work and completion event.

    New workflow connects an event to an agent task. Specify a name, the event and the instruction. The full YAML form has a rules list. This example starts from an issue label, asks an agent to prepare a pull request and waits for a merge event.

    first-run.yamlDownload

    rules:
  - name: first-run
    on: plane.label_added
    if: { label: first-run }
    do:
      - agent: { type: first-run, context: "Fix {issue.title} and open a pull request." }
      - plane.comment: "Picked up. The pull request is linked in the run."
    verify:
      on: github.pr.merged
      within: 24h
    finally:
      - matrix.send: "[{_status}] first-run {issue.title}"

    Validated against the Recuriant workflow parser on 2026-11-02. Workflow language version 1.

    Recuriant validates a workflow before saving it. With a declared policy, mutating steps are checked before execution: by default, L1 runs, L2 waits for approval and L3 is refused.

    How tiers are applied
  3. 3

    Inspect the run.

    Label an issue to start the workflow. In Executions, inspect each step's result and duration. An agent dispatch links to the agent's execution. Held actions appear in Approvals.

    1. first-run on plane.label_added first-run started
    2. first-run agent type=first-run dispatched
    3. first-run plane.comment L1 · ran
    4. first-run verify github.pr.merged within 24h watching until tomorrow 09:12
    Illustrative example with fictional data

    Run results and available policy decisions can also be read through the API. Allow and deny audit writes are best effort; held approval state requires storage.

Authenticate with an API key.

Every request carries a key as a bearer token. Requests go to the API address you receive with your workspace; the examples call it $RECURIANT_API.

  • Create a key in the app under API Keys. Give it a name and an expiry of 30 days, 90 days, one year or never. The key is shown once, so copy it then.
  • A key that starts with ck_ acts for the person who created it. A key that starts with cka_ belongs to a managed agent and carries only the scopes of that agent's role.
  • A key can call actions and read runs. It cannot approve a held step: approvals need a human login.
  • Revoke a key from the same screen when you no longer need it.

Check a key

curl "$RECURIANT_API/me" -H "Authorization: Bearer $RECURIANT_API_KEY"

API reference.

Use the API address supplied with your workspace. Bodies are JSON, and /openapi.json serves the machine-readable schema. The examples below show selected response fields.

GET /me who you are

Returns the person or agent behind the key and the workspace it belongs to.

Request

curl "$RECURIANT_API/me" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Response, abridged

{
  "sub": "<id>",
  "email": "<email>",
  "username": "ana",
  "tenant": {
    "id": "<id>",
    "slug": "acme",
    "name": "acme"
  },
  "role": "",
  "principal_type": "user",
  "principal_id": "<id>"
}
GET /workflows your workflows

Lists each workflow with its trigger, conditions, steps and whether it declares a verification.

Request

curl "$RECURIANT_API/workflows" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Response, abridged

{
  "workflows": [
    {
      "name": "first-run",
      "on": "plane.label_added",
      "conditions": {
        "label": "first-run"
      },
      "steps": 2,
      "do": [
        {
          "action": "agent"
        },
        {
          "action": "plane.comment"
        }
      ],
      "has_verify": true
    }
  ],
  "defaults": {}
}
GET /actions the action catalog

Lists every action your key can call, with its inputs, whether it changes anything outside Recuriant, its reversibility, impact and tier.

Request

curl "$RECURIANT_API/actions" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Response, abridged

{
  "tenant": "acme",
  "actions": [
    {
      "name": "matrix.send",
      "kind": "connector",
      "mutates_external_state": true,
      "reversibility": "reversible",
      "impact": "low",
      "tier": "L1"
    }
  ],
  "total": 1
}
POST /actions/{action} call one action

Runs an action by name through the configured execution checks. Put the action's arguments under args. A call that continues in the background returns 202 with a status URL in data.

Request

curl -X POST "$RECURIANT_API/actions/matrix.send" \
  -H "Authorization: Bearer $RECURIANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"args": {"body": "Deploy complete"}}'

Response, abridged

{
  "ok": true,
  "output": "<the action output>",
  "data": {}
}
POST /dry-run preview an event

Explains which workflows match a sample event and why. It dispatches no work and records no policy decision. With explain set, the response also includes workflows that did not match.

Request

curl -X POST "$RECURIANT_API/dry-run" \
  -H "Authorization: Bearer $RECURIANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "plane.label_added", "vars": {"label": "first-run"}, "explain": true}'

Response, abridged

{
  "event": "plane.label_added",
  "vars": {
    "label": "first-run"
  },
  "matched_workflows": 1,
  "total_evaluated": 1,
  "matches": [
    {
      "workflow": "first-run",
      "matched": true
    }
  ],
  "results": [
    {
      "workflow": "first-run",
      "matched": true
    }
  ]
}
GET /executions list runs

Lists runs. Filter by workflow, type, status or issue. A list leaves out step logs; read one run for the full record.

Request

curl "$RECURIANT_API/executions?workflow=first-run" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Response, abridged

[
  {
    "id": "<id>",
    "type": "workflow",
    "status": "completed",
    "workflow_name": "first-run",
    "event_type": "plane.label_added",
    "started_at": "2026-11-02 09:10:04+00:00",
    "finished_at": "2026-11-02 09:12:41+00:00",
    "details_included": false,
    "step_log": null
  }
]
GET /executions/{id} read one run

Returns one run with its step log, the run that started it, the current step and its nesting depth.

Request

curl "$RECURIANT_API/executions/<id>" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Response, abridged

{
  "id": "<id>",
  "type": "workflow",
  "status": "completed",
  "workflow_name": "first-run",
  "parent_execution_id": null,
  "current_step": 2,
  "total_steps": 2,
  "depth": 0,
  "details_included": true
}

Find the actions your workspace exposes.

Your catalog lists the actions your credentials allow. A connector's actions appear once its integration is configured for your workspace and disappear when it is turned off.

A managed agent's key lists read-only actions, workflows and the actions on its role, and nothing else. Each action declares how reversible it is and how far it reaches, and that sets its tier.

plane.comment
reversible, low impact: L1, runs
plane.issue
reversible, low impact: L1, runs
matrix.send
reversible, low impact: L1, runs
http
hard to undo, low impact: L2, waits for a person
llm
read-only: no gate
grafana.query_metrics
read-only: no gate

Connect an MCP client.

Recuriant's MCP server exposes workflows, runs, approval records and connector actions to compatible clients such as Claude Code or Cursor. Actions use the same configured checks as workflow steps. The server is not yet published as an installable package; contact the team to discuss access.

It authenticates with the same ck_ or cka_ key as the API.

Discuss MCP access

Configure action policy.

With a declared policy, mutating steps are checked after their inputs are resolved and before execution. Your policy maps the default tiers below to allow, gate or deny.

L1
Reversible and low impact. The step runs. Its allow decision is written best effort unless the operation requires persistence.
L2
Other mutating actions, including unclassified actions. The step waits for a named approver, for 24 hours by default. Expiry denies the step unless the policy specifies grant or escalation. Approval state must be stored before the action can proceed.
L3
Irreversible with medium or high impact, or hard to undo with high impact. The step is refused; an available decision record identifies the rule.
No policy declared
Without a declared policy, workflow steps run ungoverned and no policy approval is held. Applicable identity scopes are still checked.
policy_unavailable
A declared policy that cannot be loaded blocks every action that would change an external system.
Read the full governance model

Check for the expected event.

A workflow can define an event that represents completion and a deadline. After its steps, the run waits for that event. If the deadline passes first, it records the missed outcome and runs the follow-up steps configured for that case.

incident-resolution.yamlDownload

rules:
  - name: incident-resolution
    on: alertmanager.firing
    if: { severity: critical }
    do:
      - agent: { type: incident, context: "Diagnose {alert.name} and propose one change." }
        as: diagnosis
      - plane.issue: { title: "[INCIDENT] {alert.name}", description: "{diagnosis}" }
      - http: { url: "https://deploy.example.com/rollback", method: POST, body: { service: "{alert.namespace}" } }
    verify:
      on: alertmanager.resolved
      within: 30m
      else:
        - alert: { severity: critical, summary: "{alert.name} is still firing after 30 minutes" }
    finally:
      - matrix.send: "[{_status}] incident-resolution {alert.name}"

Validated against the Recuriant workflow parser on 2026-11-02. Workflow language version 1.

  • verify.on names the expected event. within sets its deadline as a duration such as 30m or 24h. Choose an event that represents the result you need to observe.
  • else defines the steps to run when the deadline passes without the expected event.
  • finally schedules cleanup or reporting after the workflow body, including when a step fails.
  • A held action has a separate approval deadline: 24 hours by default, configured in policy. Expiry denies the action unless the policy specifies another outcome.

Understand errors and recovery.

The API returns a status code and JSON detail. Execution records show step results; available policy decisions explain why an action was allowed, held or refused.

401
The key is missing, invalid or expired. Check the Authorization header, or create a new key.
404
Unknown action. Call GET /actions for the names your workspace has.
422 invalid_action_arguments
The arguments do not match the action's inputs. The detail names the field; compare it with the inputs GET /actions lists.
202
Accepted. The work continues in the background; poll the status URL in data.
502, 503
Key validation is briefly unavailable. Your key was not judged invalid: retry with backoff.
refused · scope_missing
The action is not on the token the run carries. No approval reopens it: add the action to the agent's role or move the step to a workflow that has it.
refused · policy_unavailable
Your declared policy could not be loaded. Restore it: until it loads, every step that would change something is refused.

Pre-register to use Recuriant.

Paid access is preparing to open. Leave your work details and plan interest, and we will contact you when access is available.

Pre-register