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 path | Required scope |
|---|---|
| POST /v1/human-signal/reviews | reviews:create |
| GET /v1/human-signal/reviews/{reviewId} | reviews:read |
| POST /v1/human-signal/reviews/{reviewId}/signals | signals:create |
| GET /v1/human-signal/reviews/{reviewId}/consensus | consensus:read |
| POST /v1/human-signal/reviews/{reviewId}/cancel | reviews: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.