Concepts

The objects and identifiers used by Human In Circuit.

Organization

An organization is the account-level boundary for projects, members, API keys, reviews, callbacks, goals, and analytics. A user belongs to exactly one organization and joins through an administrator's invitation.

Project

A project is a business area for related reviews, such as Finance or Marketing. Each project owns its API keys and contains agents or automations.

Organization → Project → Agent or Automation → Workflow → Review gate
Acme         → Finance → Expense agent       → Classifier → Human review

Projects and their hierarchy are managed in Organization admin. Use an Agent for an agentic system that can reason or choose actions. Use an Automation for a deterministic n8n, Zapier, or similar process.

Workflow review gate

Each workflow has one review gate. Configure these once in Organization admin:

• approval: approve directly, or open review and edit;
• rejection feedback: reject directly, open optional feedback, or require feedback;
• rejection-reason choices;
• undo window.

Buttons and swipes use the same workflow behavior. High-risk confirmation is an approval safeguard only; it is never shown while rejecting.

Agent

An agent or automation is created beneath a project. A workflow is created beneath that system and has a stable, project-scoped workflow_key. Send that key with the review; Human In Circuit resolves the display names and applies the administrator's review gate. Optional request agent fields such as model, prompt version, and tags are context only and never control review behavior.

Roles

• Reviewer: review work and view analytics.
• Manager: also create agents, automations, workflows, gates, and goals.
• Admin: also manage projects, API keys, callbacks, invitations, and standard roles.
• Owner: also appoint Admins and request organization deletion.

Goals

Managers can set review-count goals for the whole organization or one project, agent, automation, or workflow. Progress appears on the Goals page and directly beside the matching item in Admin → Agents & workflows. The goal setter is the default completion-alert recipient and can choose another active member.

Project key

Every project has a permanent, readable project key such as:

customer-support

Use it to distinguish reviews and callback events from different projects. You can find it in three places:

1. Organization admin → Projects: expand a project and copy its key.
2. The response from POST /v1/reviews.
3. The review.resolved callback body.

The project key is not a review identifier. One project can contain many reviews, and every review has its own review_id.

API key

An API key authenticates an integration. Every API key belongs to exactly one project; a single key cannot submit reviews to multiple projects.

The complete API key is shown only once when it is created. Organization admin later shows its name, prefix, project, callback access, status, creation date, and last-used date. The API key selects the project; review requests do not send a project ID or project key.

Review

A review is a durable request for human judgment. It can contain:

• a title and short summary;
• longer Markdown context;
• editable or read-only fields;
• initial values;
• priority and risk;
• attachments;
• caller-owned metadata;
• a callback URL.

Contract versions

Versioning happens at four separate boundaries:

Every existing and newly generated API key is pinned to v1. Omitting schema_version and callback.version is backward compatible and selects review.v1 and callback.v1. The accepted response returns the versions that were stored; idempotent replays return the original review's versions.

A workflow and its review gate have monotonically increasing revisions. Review creation stores the workflow revision plus an effective-policy snapshot. Later admin edits reach pending reviews too, so an old pending review never silently changes under a reviewer or connected workflow.

Additive fields may appear within v1. A future breaking request or response uses a new URL major such as /v2; a breaking callback uses a new callback version. Existing keys and reviews are not upgraded automatically.

Priority

priority accepts exactly four values:

Priority is about timing and attention. Use risk separately to communicate the consequence of an incorrect approval.

Metadata pass-through

Use metadata for IDs and routing context owned by your application:

{
  "metadata": {
    "ticket_id": "ticket-1842",
    "customer_id": "cus_9281",
    "routing": {
      "team": "billing"
    }
  }
}

Metadata can contain any JSON values up to 16 KB. Human In Circuit stores it with the review and returns it unchanged from POST /v1/reviews, GET /v1/reviews/{review_id}, and the review.resolved callback. It is not shown to reviewers. Do not put secrets in metadata.

Fields

Fields determine what the reviewer sees or edits.

Use the Review playground to switch between complete use cases, edit the request JSON, and see how these fields render on mobile.

Text

• text: short, single-line text.
• textarea: longer, multi-line text.
• email: an email address.
• url: a web address.

{
  "key": "reply",
  "label": "Customer reply",
  "type": "textarea",
  "description": "Edit the generated reply before approval.",
  "required": true
}

The field key connects the schema to initial_values:

{
  "initial_values": {
    "reply": "Hello! This is the generated draft."
  }
}

The mobile review card renders a labelled multi-line editor containing that draft.

initial_values is the canonical request property. For workflow tools, you can send the same object as output; the API maps it to initial_values when the canonical property is omitted or empty. After approval, the callback returns the human-edited object in both final_values and the developer-friendly output alias. If neither request property contains values, both callback objects will correctly be empty.

description is the field's helper text. It appears directly below the control, so use it to tell the reviewer what to verify, edit, or preserve. Keep implementation details in metadata or details_markdown instead.

Choice

• select: choose one option.
• multiselect: choose multiple options.
• boolean: yes/no.

Choice fields use labelled options:

{
  "key": "tone",
  "label": "Tone",
  "type": "select",
  "options": [
    { "label": "Friendly", "value": "friendly" },
    { "label": "Formal", "value": "formal" }
  ]
}

Numbers and dates

• number
• date
• time
• datetime

Read-only

Use readonly for context that the reviewer should see but cannot change.

Decision

A completed decision has an outcome of:

• approved
• rejected

Approved decisions return final_values, including human edits. Rejected decisions may return rejection_reasons and a note.

Callback

When a review has callback.url, Human In Circuit sends a review.resolved event after the decision is committed.

Polling

Store the review_id and call GET /v1/reviews/{review_id} to retrieve the current state. Review results are stored in the database; they do not disappear when callback retries end.