NODRANetwork
Documentation · ES
Back to Integrations in the Partner dashboard

HUMAN SIGNAL / NODRA PROTOCOL

Integrate human review into an AI agent with an API

Verified Human Signal routes, Partner authentication, polling and webhook responsibilities.

Updated · NODRA Network

The integration boundary is the same for an AI agent, chatbot or internal copilot: your backend calls the Human Signal API when your policy requires human input. Keep credentials on the server. The Partner owns the reviewer interface and reviewer authorization.

Access and authentication

Obtain an approved base URL and Partner credential through NODRA. Send x-nodra-api-key or Authorization: Bearer …. Tenant, Client, environment and scopes are bound to the credential. An API key is not an administrative dashboard login. Sandbox credentials and production credentials are distinct.

Implemented Partner routes

Method and pathRequired scope
POST /v1/human-signal/reviewsreviews:create
GET /v1/human-signal/reviews/{reviewId}reviews:read
POST /v1/human-signal/reviews/{reviewId}/signalssignals:create
GET /v1/human-signal/reviews/{reviewId}/consensusconsensus:read
POST /v1/human-signal/reviews/{reviewId}/cancelreviews:cancel

GET /v1/human-signal/account returns the authenticated Partner account and access information. Availability and quotas depend on the credential. These routes are a reference to the implemented boundary, not an anonymous public API.

Create a review

After access is approved, use a unique Idempotency-Key and a synthetic test payload such as:

{
  "provider": "simulated-ai",
  "model": "demo-model",
  "title": "Procedure review",
  "purpose": "Check a draft before use",
  "aiResponse": "Draft answer requiring human context.",
  "language": "en",
  "category": "technology"
}

Persist the returned case identifier. Expose the case only to authorized reviewers, retrieve its state and consensus, and handle insufficient signals, cancellation and timeout. Signal collection and closure thresholds are agreed for the selected workflow.

Run the downloadable example

Download the dependency-free Node.js example. It defaults to a synthetic walkthrough; it does not contact NODRA or generate real reviewer votes.

node human-signal-client.mjs --mock
# Read-only account check after approved access:
NODRA_BASE_URL='https://YOUR-APPROVED-ENDPOINT' NODRA_API_KEY='YOUR-SERVER-SIDE-KEY' node human-signal-client.mjs --account

Responses and failure handling

Responses use ok, data, error and meta. Handle authentication failures (401), scope/access failures (403), unavailable cases (404), invalid input (400), idempotency conflicts (409) and rate or quota limits (429). Honor retryability and use bounded backoff rather than indefinite retries.

Webhooks

When enabled, use HTTPS, verify the agreed signature, accept duplicate delivery idempotently and retrieve canonical case state when needed. Webhook delivery does not turn human review into an instantaneous operation. Keep API keys, webhook secrets and private case data out of public content.