REST API

POST /v1/signup

Auth: public · MCP create_tenant

Request

{
  "tenantName": "Acme Agents",
  "ownerEmail": "ops@example.com",
  "ownerName": "Ops",
  "password": "change-me-now"
}

password min 8 characters.

Response data

{
  "tenant": { /* Tenant */ },
  "user": { /* AppUser, role admin */ },
  "adminApiKey": "ak_…",
  "adminApiKeyRecord": { /* ApiKeyRecord without keyHash */ },
  "consumerApiKey": "ak_…",
  "consumerApiKeyRecord": { /* ApiKeyRecord without keyHash */ },
  "apiKey": "ak_…"
}

apiKey is a deprecated alias of adminApiKey.

POST /v1/auth/signin

Auth: public

Request

{ "email": "ops@example.com", "password": "…" }

Response data

{ "tokens": { /* Cognito AuthResult */ }, "user": { /* AppUser */ } }

POST /v1/auth/refresh

Auth: public

Request

{ "refreshToken": "…" }

Response data

{ "tokens": { /* Cognito AuthResult */ } }

POST /v1/auth/forgot-password

Auth: public

Request

{ "email": "ops@example.com" }

Response data

{ "sent": true }

POST /v1/auth/confirm-forgot-password

Auth: public

Request

{
  "email": "ops@example.com",
  "code": "123456",
  "newPassword": "NewPass1"
}

code is 6 characters. Password: min 8, must include digit, upper, and lower case.

Response data

{ "reset": true }

GET /v1/me

Auth: tenant

Response data

// user session
{ "user": { /* AppUser */ }, "role": "admin" | "consumer" }

// API key session
{ "apiKey": { /* ApiKeyRecord without keyHash */ }, "role": "admin" | "consumer" }

POST /v1/review-requests

Auth: tenant · MCP reviews (create)

Request

{
  "title": "Approve landing page",
  "description": "optional",
  "externalId": "landing-page-v2",
  "domain": "landing-pages",
  "smartPrecheck": { "enabled": true, "instructions": "…", "blockOn": "major" },
  "policy": { "type": "ALL_APPROVE", "decisionScope": "request" },
  "reviewers": [{ "email": "reviewer@example.com", "name": "Alex", "channel": "email" }],
  "subscribers": ["ops@example.com"],
  "items": [{
    "id": "optional-client-id",
    "title": "Preview",
    "externalId": "preview-asset-1",
    "document": { "type": "url", "url": "https://example.com/page" },
    "metadata": { "branch": "main" }
  }],
  "metadata": { "env": "staging" }
}

Response data

{
  "request": { /* ReviewRequest, status pending */ },
  "items": [ /* ReviewItem */ ],
  "reviewers": [{
    "reviewerId": "reviewer_…",
    "email": "reviewer@example.com",
    "name": "Alex",
    "channel": "email",
    "decision": "pending",
    "authCodeExpiresAt": "…"
  }],
  "reviewerLinks": [ /* only reviewers you have to deliver to yourself; see Channels */ ],
  "next_actions": [
    "wait_for_reviewers",
    "fetch_review_request",
    "open_dashboard"
  ]
}

With smartPrecheck.enabled (or enabledByDefault on the domain config), no email is sent: the request comes back as precheck_running with a queued precheck and next_actions: ["wait_for_precheck", "fetch_precheck"]. See Smart precheck.

Reviewer delivery channels

reviewers[].channel decides who delivers the review link. It defaults to email, which is the behaviour every existing request already has.

email  AgentFabric emails the invitation, the reminders and the activity digests.
none   AgentFabric mints the link and sends nothing. You deliver it — your product,
       your chat, your agent — and reminder/digest emails are skipped for that reviewer.

A none reviewer's link comes back in reviewerLinks on create, POST …/reviewers and POST …/remind:

{
  "reviewerId": "reviewer_…",
  "email": "agent@example.com",
  "channel": "none",
  "reviewUrl": "https://review.agentfabric.dev/review?authCode=rrc_…",
  "sent": false
}

The list is empty when every reviewer is on email, so an empty list means nothing is owed. Since no digest email goes out for that reviewer, the review_comment.created webhook is how you learn about their replies. Treat reviewUrl as a credential: it authenticates as that reviewer.

GET /v1/review-requests

Auth: tenant · MCP reviews (list)

Query: optional filter[externalId]. Newest first.

Response data

[
  {
    /* ReviewRequest fields… */
    "outcome": { /* Outcome */ },
    "evaluationScope": "request" | "item",
    "itemOutcomes": [{ "itemId": "item_…", "status": "pending" }]
  }
]

Cancelled/expired rows omit presentation fields.

GET /v1/review-requests/{requestId}

Auth: tenant · MCP reviews (get)

Response data

{
  "request": { /* ReviewRequest */ },
  "items": [ /* ReviewItem */ ],
  "reviewers": [ /* Reviewer */ ],
  "itemDecisions": [ /* ReviewItemDecision */ ],
  "comments": [ /* ReviewComment */ ],
  "notices": [ /* ReviewNotice: pending activity digests */ ],
  "events": [ /* AuditEvent */ ],
  "outcome": { /* Outcome */ },
  "precheck": { /* latest Precheck, when the gate has run */ },
  "evaluationScope": "request" | "item",
  "itemOutcomes": [{ "itemId": "item_…", "status": "approved" }]
}

Comment snapshots and precheck evidence come back as short-lived presigned URLs.

GET /v1/review-requests/{requestId}/items

Auth: tenant

Response data

[ /* ReviewItem */ ]

GET /v1/review-items

Auth: tenant · MCP reviews (list_items)

Query: filter[externalId] required. Newest first.

Response data

{
  "items": [{
    "requestId": "rr_…",
    "request": { /* ReviewRequest */ },
    "item": { /* ReviewItem */ }
  }]
}

GET /v1/review-requests/{requestId}/comments

Auth: tenant · MCP comments (list)

Query: optional itemId, status=open|resolved. Replies follow their thread root, and a status filter keeps or drops whole threads.

Response data

[ /* ReviewComment */ ]

POST /v1/review-requests/{requestId}/comments

Auth: tenant · MCP comments (create)

Request

{
  "body": "Which price did you expect?",
  "parentCommentId": "comment_…",
  "reviewerId": "reviewer_…",
  "itemId": "item_…"
}

Pass parentCommentId to reply inside a thread; the reply inherits that thread's itemId. Pass reviewerId instead to open a new thread aimed at one reviewer. 404 if the parent comment or reviewer does not exist, 410 if cancelled.

Response data

{ /* ReviewComment */, "notifyAfter": "2026-07-09T10:30:00.000Z" }

notifyAfter is when the reviewer's digest email goes out unless there is more activity.

POST /v1/review-requests/{requestId}/notify

Auth: tenant · MCP comments (notify)

Request

{ "reviewerIds": ["reviewer_…"] }

Sends pending replies immediately instead of waiting out the quiet period. Omit reviewerIds to flush every reviewer with unsent replies. 410 if cancelled or expired.

Response data

{
  "notified": [{
    "reviewerId": "reviewer_…",
    "outcome": "sent" | "idle" | "claimed_by_other",
    "recipients": ["reviewer@example.com"]
  }]
}

POST /v1/review-requests/{requestId}/comments/{commentId}/resolve

Auth: tenant · MCP comments (resolve)

No body. Sets resolvedBy to the caller email or api-key:{label}. Resolution is per thread, so commentId must be the comment that started it — a reply returns 400.

Response data

{ /* ReviewComment, status resolved */ }

POST /v1/review-requests/{requestId}/comments/{commentId}/unresolve

Auth: tenant · MCP comments (unresolve)

Thread root only, same as resolve.

Response data

{ /* ReviewComment, status open */ }

POST /v1/review-requests/{requestId}/reviewers

Auth: tenant · MCP reviews (add_reviewer)

Request

{
  "reviewers": [{ "email": "new@example.com", "name": "Sam" }]
}

409 if email already assigned.

Response data

{ /* added reviewers (same shape as create) */ }

POST /v1/review-requests/{requestId}/remind

Auth: tenant · MCP reviews (remind)

Request

{ "emails": ["reviewer@example.com"] }

emails optional — defaults to all pending reviewers. Regenerates auth codes. 410 if cancelled/expired.

Response data

{
  "reminded": [
    { "reviewerId": "reviewer_…", "email": "reviewer@example.com", "sent": true }
  ]
}

POST /v1/review-requests/{requestId}/cancel

Auth: tenant · MCP reviews (cancel)

Response data

{ "status": "cancelled" }

GET /v1/review-requests/{requestId}/precheck

Auth: tenant · MCP precheck (get)

Response data

{
  "precheck": { /* latest Precheck */ },
  "history": [ /* Precheck, newest attempt first */ ]
}

Findings carry presigned evidenceUrl screenshots.

POST /v1/review-requests/{requestId}/precheck/rerun

Auth: tenant · MCP precheck (rerun)

No body. Queues attempt N+1 and moves the request back to precheck_running. 409 if the gate is not enabled, 410 if cancelled/expired.

Response data

{ "precheck": { /* Precheck, status queued */ } }

POST /v1/review-requests/{requestId}/precheck/override

Auth: tenant · MCP precheck (override)

No body. Sends the reviewer invitations despite a failed gate and records a precheck_overridden audit event. 409 if the request is not held by the gate.

Response data

{ "status": "pending", "released": 2 }

GET /v1/feedback-groups

Auth: tenant · MCP feedback (list)

Query: domain (default default), optional status=active|muted|archived.

Response data

{ "domain": "landing-pages", "groups": [ /* FeedbackGroup */ ] }

GET /v1/feedback-groups/{groupId}

Auth: tenant · MCP feedback (get)

Query: domain.

Response data

{
  "group": { /* FeedbackGroup */ },
  "members": [{
    "commentId": "comment_…",
    "requestId": "rr_…",
    "itemId": "item_…",
    "excerpt": "Price says 19 but the ad said 9",
    "snapshotUrl": "presigned png url",
    "createdAt": "…"
  }]
}

PATCH /v1/feedback-groups/{groupId}

Auth: tenant · MCP feedback (update)

Request

{
  "status": "active" | "muted" | "archived",
  "rule": "rewritten check the precheck should enforce",
  "severity": "critical" | "major" | "minor",
  "title": "…"
}

All fields optional. Muted and archived groups are excluded from the precheck prompt.

Response data

{ /* FeedbackGroup */ }

GET /v1/precheck-config

Auth: tenant

Query: domain.

Response data

{
  "config": { /* PrecheckConfig */ },
  "domains": [{
    "domain": "landing-pages",
    "requestCount": 12,
    "activeGroupCount": 4,
    "gateEnabledByDefault": true,
    "configured": true
  }]
}

domains covers every domain in use, including those that only ever appeared on a review request. configured is false for those.

PUT /v1/precheck-config

Auth: tenant · MCP precheck (configure)

Request

{
  "domain": "landing-pages",
  "instructions": "Walk the full page and submit the signup form.",
  "blockOn": "major",
  "enabledByDefault": true,
  "learnFromFeedback": true,
  "maxGroups": 60
}

All fields optional; domain may also be given as a query parameter.

Response data

{ /* PrecheckConfig */ }

POST /v1/checks

Auth: tenant · MCP checks (create)

Request

{
  "title": "Pre-flight check",
  "description": "optional context for the agent",
  "items": [{ "title": "Landing page", "document": { "type": "url", "url": "https://…" } }],
  "domain": "landing-pages",
  "instructions": "added on top of the domain instructions",
  "model": "grok-4.5",
  "blockOn": "major",
  "metadata": { }
}

Only items is required; everything else falls back to the domain configuration.

Response data

{
  "check": { /* Check */ },
  "next_actions": ["wait_for_check", "fetch_check"]
}

GET /v1/checks/{checkId}

Auth: tenant · MCP checks (get)

Response data

{ "check": { /* Check, with presigned evidence urls */ } }

Poll until status leaves queued/running. A blocked run is failed with findings; error means the check itself could not complete.

GET /v1/users

Auth: admin · MCP users (list)

Response data

[ /* AppUser */ ]

POST /v1/users

Auth: admin · MCP users (create)

Request

{
  "email": "dev@example.com",
  "name": "Dev",
  "role": "consumer"
}

role defaults to consumer.

Response data

{
  "user": { /* AppUser */ },
  "temporaryPassword": "…"
}

PATCH /v1/users/{userId}

Auth: admin

Request

{ "role": "admin" | "consumer" }

Response data

{ /* AppUser */ }

400 if demoting the last admin.

DELETE /v1/users/{userId}

Auth: admin

Response data

{ "userId": "user_…", "deleted": true }

400 if deleting yourself or the last admin.

GET /v1/api-keys

Auth: admin · MCP api_keys (list)

Response data

[ /* ApiKeyRecord without keyHash; active only */ ]

POST /v1/api-keys

Auth: admin · MCP api_keys (create)

Request

{ "label": "CI consumer", "scope": "consumer" }

scope defaults to consumer.

Response data

{
  "apiKey": "ak_…",
  "apiKeyRecord": { /* ApiKeyRecord without keyHash */ }
}

POST /v1/api-keys/{keyId}/revoke

Auth: admin

Response data

{ "keyId": "key_…", "status": "revoked" }

POST /v1/api-keys/{keyId}/rotate

Auth: admin

Revokes the old key and creates a new admin key labeled Rotated API key.

Response data

{
  "apiKey": "ak_…",
  "apiKeyRecord": { /* ApiKeyRecord without keyHash */ }
}

GET /v1/webhooks

Auth: admin · MCP webhooks (list)

Response data

{
  "webhooks": [ /* WebhookEndpoint, secret replaced by secretHint */ ],
  "events": [ /* every event type you can subscribe to */ ]
}

POST /v1/webhooks

Auth: admin · MCP webhooks (create)

Request

{
  "url": "https://agent.example.com/hooks/agentfabric",
  "description": "Content agent",
  "events": ["review_request.decided", "review_comment.created"]
}

Omit events to receive all of them. The url must be public https — loopback, private ranges and the instance metadata address are rejected with 400.

Response data

{
  "webhook": { /* WebhookEndpoint */ },
  "secret": "whsec_…"
}

The secret is returned once; later reads only show a hint. See Webhooks for the signature to verify with it.

DELETE /v1/webhooks/{endpointId}

Auth: admin · MCP webhooks (delete)

Response data

{ "deleted": true }

404 if the tenant has no such endpoint.

POST /v1/review/exchange

Auth: public

Request

{ "authCode": "rrc_…" }

Response data

{
  "token": "rrc_…",
  "requestId": "rr_…",
  "reviewerId": "reviewer_…"
}

GET /v1/review/{requestId}

Auth: reviewer (Bearer auth code or ?authCode=)

Response data

{
  "request": { /* ReviewRequest */ },
  "items": [ /* ReviewItem */ ],
  "reviewer": { /* Reviewer (this reviewer) */ },
  "itemDecisions": [ /* this reviewer's item decisions */ ],
  "comments": [ /* ReviewComment */ ],
  "deleted": false,
  "evaluationScope": "request" | "item",
  "reviewerAggregate": "pending" | "approved" | "rejected" | "changes_required"
}

POST /v1/review/{requestId}/opened

Auth: reviewer

Records a link_opened audit event.

GET /v1/review/{requestId}/comments

Auth: reviewer

Query: optional itemId, status.

Response data

[ /* ReviewComment */ ]

POST /v1/review/{requestId}/comments

Auth: reviewer

Request

{
  "body": "Please fix the hero CTA.",
  "itemId": "item_…",
  "parentCommentId": "comment_…",
  "metadata": { }
}

Pass parentCommentId to answer a reply from the team. 410 if cancelled.

Response data

{ /* ReviewComment */ }

POST /v1/review/{requestId}/notify

Auth: reviewer

No body. The "I'm done" signal: emails the tenant's subscribers a digest of this reviewer's comments and verdicts now, instead of waiting out the 30-minute quiet period.

Response data

{ "outcome": "sent" | "idle" | "claimed_by_other", "recipients": ["team@example.com"] }

POST /v1/review/{requestId}/decision

Auth: reviewer

Request

{
  "decision": "approved" | "rejected" | "changes_required",
  "itemId": "item_…",
  "comment": "optional note (creates a comment)"
}

Response data

{
  "status": "pending" | "approved" | "rejected" | "changes_required" | …,
  "itemDecision": { /* ReviewItemDecision, if itemId set */ },
  "reviewerAggregate": "pending" | "approved" | "rejected" | "changes_required"
}