The DueReason API lets your team, pipelines and AI agents ask a person for approval before they act, and keeps the reasons on record. List the actions your organization accepts, request approval with a payload and a reason, wait for the grant, verify it, then execute and report back. Each step is a ledgered event, and a signed, independently verifiable receipt closes the loop.
List the actions your organization accepts approval requests for with GET /actions, each with the payload schema a request must satisfy.
Ask for approval: POST /approvals with the action, an exact payload and your reason. The organization's workflows decide who must approve; a request matching no workflow is refused up front with no_workflow.
Wait for the approval.approved or approval.rejected webhook, or poll GET /approvals/{id}?wait=N. Never act before the request is approved.
Verify the grant POST /grants/verify returns before you rely on it, or check its signature yourself against the organization's JWKS.
Carry out the approved action, then report what happened with POST /approvals/{id}/executions. A grant is single-use.
Fetch the signed decision receipt with GET /approvals/{id}/receipt: a self-contained record you, an approver or an auditor can verify without a DueReason account.
Authentication
Every request carries an API key as a bearer token. Owners and admins create keys in the console under Settings, API keys, optionally with an expiry; the full key is shown once, DueReason stores only its SHA-256 hash.
A missing, malformed, expired or revoked key gets 401. A valid key without the scope an endpoint needs gets 403 with the code insufficient_scope. Keys are never accepted in the query string.
Scopes
Scope
Allows
approval:request
Ask for approval, cancel your own pending requests, and report what happened once the grant is used.
approval:read
Read approval requests, their answers and grants; verify grants.
action:read
Read the actions you may ask approval for and their payload schemas.
action:manage
Create, update and delete actions and workflows (config as code). Not granted by default; never combinable with approval:request on the same key, since that key could then auto-approve its own requests. Writes are audited with the key as actor, and turning autoApprove on emails the organization's owners.
mandate:read
Read mandates and their usage.
mandate:revoke
Revoke a mandate your organization issued.
webhook:manage
Create and list webhook endpoints, and read their signing secret once, at creation.
Platform-work module (off by default)
Scope
Allows
decision:read
Read decisions, their ledger events and the ledger head.
decision:request
Create and withdraw decisions, relay review requests.
decision:enact
Confirm that a decision has taken effect.
statement:issue
Issue statements of reasons and receive worker portal links.
worker:read
Read worker records.
worker:write
Create and update worker records.
system:read
Read the register of automated systems.
notice:read
Read DSA notices (DSA add-on).
notice:write
Relay DSA notices received through your own interface (DSA add-on).
No scope can answer an approval request: only the people a workflow names can respond, in the console or from a notification.
Idempotency
Every POST requires an Idempotency-Key header: any string of 1 to 200 characters that you generate once per logical operation, such as a UUID. Retrying with the same key never repeats the effect.
Same key and the same request (method, path and body): you get the original status and body again, byte for byte, with the header Idempotent-Replayed: true.
Same key with a different request: 422 with the code idempotency_key_reused.
Same key while the first request is still running: 409 with the code idempotency_key_in_use. Retry after a short pause.
Only successful responses are remembered. A request that failed changed nothing, so retrying it with the same key runs it again, for example after a reviewer has approved the decision.
Keys are remembered for 24 hours. PUT is idempotent by definition and does not take the header.
Rate limits
Each API key may make up to 600 requests a minute, counted in a fixed one-minute window and enforced per key, not per organization or IP address. A key shared by several workers or agents draws from the same budget, and every response, successful or not, carries the three headers below.
Header
Meaning
RateLimit-Limit
The limit for the current window: 600.
RateLimit-Remaining
Requests left in the current window.
RateLimit-Reset
Seconds until the window resets.
Exceeding the limit answers 429 with the problem code rate_limited and a Retry-After header giving the number of seconds to wait.
Example 429 response
{
"type": "https://www.duereason.com/docs/api#error-rate_limited",
"title": "Too many requests",
"status": 429,
"detail": "This API key made more than 600 requests in a minute. Retry after 12 s.",
"code": "rate_limited",
"details": {
"limit": 600,
"retryAfterSeconds": 12
}
}
Back off for Retry-After seconds rather than a fixed delay. @duereason/sdk already retries 429s this way automatically; you only need to handle this yourself when you call the REST API directly.
CORS
Every /api/v1 operation allows cross-origin requests from any browser origin, the same policy already used for /api/v1/openapi.json. The API key is a bearer token you send explicitly in the Authorization header, never an ambient credential like a cookie, so there is no CSRF-style risk in that choice; it means a browser-based integration (an internal admin page, a Retool/Glide custom component) gets DueReason's real problem+json errors instead of an opaque network failure.
Every response carries the headers below. A preflighted request (anything with a custom header, such as Authorization or Idempotency-Key) gets a 204 with the same headers from an OPTIONS request that never reaches authentication.
Errors
Errors are RFC 9457 problem documents with the media type application/problem+json. Branch on code, which is stable; detail is a human-readable explanation that is safe to log. Validation errors list each problem in details.issues with its location (path, query or body) and field path.
{
"type": "https://www.duereason.com/docs/api#error-invalid",
"title": "Invalid request",
"status": 422,
"detail": "The request body is invalid.",
"code": "invalid",
"details": {
"issues": [
{
"in": "body",
"path": "facts",
"message": "Invalid input: expected string, received undefined"
}
]
}
}
Code
Status
Meaning
malformed_json
400
The body is not valid JSON.
idempotency_key_required
400
A POST without an Idempotency-Key header, or with one longer than 200 characters.
unauthorized
401
The API key is missing, malformed, expired or revoked.
payment_required
402
The organization's subscription has lapsed, so new approval requests and decisions are refused; details.billingUrl is where an owner or admin chooses a plan. Reads, cancelling, reporting executions and verifying grants keep working.
insufficient_scope
403
The key does not have the scope this endpoint needs; details.requiredScope names it.
forbidden
403
The action is not allowed for an API key at all.
not_found
404
No such resource in your organization. Another organization's ids also give 404.
conflict
409
The decision is not in a state that allows this, for example enacting a decision that is still pending_human, or the externalRef is taken.
not_pending
409
The approval request is not in a state that allows this: cancelling a request that is already decided, or reporting an execution for one that is not approved.
not_decided
409
The request has not been decided yet; a receipt exists once it is approved, rejected, expired or cancelled.
already_responded
409
This person has already answered the request (console only).
already_executed
409
An execution was already reported for this grant; a grant is single-use.
idempotency_key_in_use
409
A request with the same Idempotency-Key is still running.
precondition_failed
412
Something else must happen first, for example activating the cited system, or the person is a P2B business user to whom Art. 11 does not apply. Notice endpoints also answer 412 while the DSA add-on is off.
payload_too_large
413
The body is larger than 256 KB.
unsupported_media_type
415
The body is not sent as application/json.
invalid
422
The request failed validation; details.issues lists every problem.
no_workflow
422
No active workflow of the action applies to the request, so it cannot be approved. Nothing was created.
invalid_payload
422
The payload does not satisfy the action's payload schema; details.problems lists why.
idempotency_key_reused
422
The Idempotency-Key was already used for a different request.
rate_limited
429
More than 600 requests in a minute from this key. Wait for the number of seconds in Retry-After. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.
internal
500
Something failed on our side. Retrying with the same Idempotency-Key is safe.
grants_unavailable
503
The request is approved but its grant cannot be signed right now, a configuration problem on our side. Retry later.
scanner_unavailable
503
Files sent with a multipart POST /approvals could not be checked for malware (the scanner did not answer in time). Nothing was stored; retry in a few minutes.
Pagination
Lists return the newest items first in data, with nextCursor. Pass it as the cursor query parameter to get the next page; it is null on the last page. limit is 1 to 100, 50 by default.
Endpoints
Approvals
DueReason: ask people for approval before an agent or a system does something consequential, follow the request, and verify the signed grant before you act.
GET/api/v1/actions
List actions
The actions your organization accepts approval requests for, each with the payload schema a request must satisfy, alphabetical by key, one page at a time. Only active actions are listed by default; pass include=inactive to also see actions nobody can request against right now. Follow nextCursor (pass it back as cursor) until it is null.
Scope
action:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/actions?include=inactive" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/actions/{key}
Get an action
One action by its key, active or not, with its payload schema and grant validity.
curl -X GET "https://www.duereason.com/api/v1/actions/payment" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/actions
Create an action
Define a new kind of thing your organization accepts approval requests for: its key (immutable, what agents send as action), name, payload schema and grant validity. Requires action:manage, a scope not granted by default and never combinable with approval:request on the same key, since that key could then approve its own requests.
Change an action's name, description, payload schema, grantTtlSeconds or whether it is active. The key is immutable. Narrowing the payload schema can make requests other integrations already send start failing validation.
The approval rules your organization has configured: when each applies (its conditions), who must approve (its steps), and whether it auto-approves instead of asking a human. Newest first, one page at a time; follow nextCursor (pass it back as cursor) until it is null. A condition's value keeps its original JSON type (a boolean stays true/false, never the string "true"), so you can tell a true/false check from a text comparison. Filter by action to see only the workflows that govern it.
Scope
action:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/workflows?action=payment" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/workflows/{id}
Get a workflow
One workflow with its conditions, steps and current version.
curl -X GET "https://www.duereason.com/api/v1/workflows/wfl_0192a703e5f76a8b9c0d1e2f3a4b5c6d" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/workflows
Create a workflow
Add an approval rule for an action: its conditions, steps and whether it auto-approves. Requires action:manage. A condition's value must match the type its payload property declares (a boolean property needs true/false, never the string "yes"). Creating a workflow with autoApprove true emails the organization's owners and posts to any Slack/Teams channel subscribed to security.auto_approve_enabled, so a self-approving setup is never silent.
Change a workflow's name, description, priority, whether it is active, or replace its whole definition (conditions, autoApprove and steps together, like the console's editor — there is no way to patch a single condition). Requires action:manage. Turning autoApprove on notifies the organization's owners the same way creating one does.
Asks for approval of one action with an exact payload and a reason. The organization's workflows decide who must approve. When none applies the request is refused with no_workflow (fail closed), and a payload the action's schema rejects is refused with invalid_payload. Approvers are emailed as each step opens. Do not carry out the action until the request is approved and you hold its grant.
curl -X POST "https://www.duereason.com/api/v1/approvals" \
-H "Authorization: Bearer $DUEREASON_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"action": "payment",
"title": "Pay invoice INV-2026-118",
"reason": "Due to the reason of: the supplier'\''s invoice is due on 10 October and matches PO-77.",
"payload": {
"amount": 1200,
"currency": "EUR",
"payee": "ACME sp. z o.o.",
"invoice": "INV-2026-118"
},
"agent": {
"name": "ap-agent",
"model": "claude",
"runId": "run_8812"
},
"context": [
{
"label": "Invoice",
"url": "https://erp.example.com/invoices/INV-2026-118"
}
],
"expiresInSeconds": 86400
}'
Send multipart/form-data instead: the same request JSON as a string part, plus one or more files. Same validation, size limits and malware scan as the console.
curl -X GET "https://www.duereason.com/api/v1/approvals?status=pending&action=payment&q=invoice%20118&limit=20" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/approvals/{id}
Get an approval request
One request with its steps, answers, evidence and, once approved, its grant. With wait=N (at most 20) the call holds until the request changes or N seconds pass, then answers. Webhooks (approval.approved, approval.rejected and the rest), or the SDK and MCP wait loops built on this call, are the primary way to learn the outcome; wait is a convenience.
The most similar decided requests of the same action in the last year, newest-scored first, each with its outcome, who decided, their written reason (truncated to 300 characters) and the evidence filenames they attached. Also a summary of every decided request in the window: counts by outcome and the most recent rejection's reason. Deterministic and local: no AI call, just similarity on the action's payload schema plus title and reason.
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/precedents?limit=5" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/approvals/{id}/comments
List an approval request's comments
The discussion thread on a request, oldest first within the page: a clarifying question, extra context, or a reply, each with who wrote it and when. Keyset-paginated, newest page first; pass nextCursor back as cursor for the page of comments older than what you already fetched.
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/comments?limit=20" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/approvals/{id}/comments
Post an approval request comment
Adds to the discussion thread on a request, attributed to the calling API key (not a named person). Requires approval:request, the same scope that creates and cancels requests. Posting never changes the request's status. Rate-limited separately from the console's own comment budget. Never parsed for @[Name](memberId)-shaped mentions, even if the body happens to contain that pattern — only the console composer's own token means a real mention.
curl -X POST "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/comments" \
-H "Authorization: Bearer $DUEREASON_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"body": "Confirmed against PO-77; the vendor matches our records."
}'
POST/api/v1/precedents/check
Check precedents before filing a request
The same similar-past-decisions search as GET /approvals/{id}/precedents, one step earlier: keyed on an action and payload you intend to send, not an existing request id, so an agent calling the API directly can see how similar requests have gone before it decides what to ask for. Optionally takes the title and reason drafted so far to sharpen the text-similarity signal. Informational only: it never blocks or changes a later POST /approvals.
Tells DueReason the grant was used, and how it went. The grant must belong to this request and must not have expired. A grant is single-use: a second report answers already_executed.
Send multipart/form-data instead: the same request JSON as a string part, plus one or more files. Same validation, size limits and malware scan as the console.
Checks a grant's signature, organization and expiry, and that it was issued for exactly this payload. For executors without a JWS library; others verify offline against the organization's keys at /.well-known/duereason/ORG-SLUG/jwks.json. An invalid grant is still a 200, with valid false and a reason.
A self-contained, signed record of this decided request: the payload and its hash, the requester, every step's responses and evidence hashes, the grant if one was issued, and the request's own ledger events. 409 not_decided while the request is still pending. See docs/duereason/receipts.md for the format and how to verify one — offline, with @duereason/sdk's verifyReceipt(), or at https://duereason.com/verify, none of which need a DueReason account.
curl -X GET "https://www.duereason.com/api/v1/approvals/apr_0192a6e1c3d54f7a8b9c0d1e2f3a4b5c/receipt" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/receipts
Export decision receipts in bulk
Every decided request's receipt whose decidedAt falls in [from, to), oldest first, cursor-paginated like the other list endpoints. Pending requests are never included. Each receipt is identical to what GET /approvals/{id}/receipt returns for that request. The range cannot exceed 92 days; page through a wider period with several calls. Built for an organization that wants its own periodic audit trail (e.g. every receipt from a quarter) without fetching each approval by hand.
curl -X GET "https://www.duereason.com/api/v1/receipts?from=2026-07-01T00:00:00Z&to=2026-10-01T00:00:00Z&limit=50" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
Mandates
Standing, bounded, revocable authority: delegate a slice of an approval decision in advance so matching requests are approved automatically, metered and ledgered. Off by default; an org owner/admin turns it on in Settings. Issued by a person in the console (Settings > Mandates) only; the API reads, checks and revokes mandates.
GET/api/v1/mandates
List mandates
Standing authority your organization has delegated, newest first. Filter by actionId or activeOnly (not revoked and within its validity window).
Scope
mandate:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/mandates" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/mandates/{id}
Get a mandate
One mandate with its constraints, limits and current-period usage.
See in advance whether a request like this would be auto-approved under a mandate, and how much budget is left on it, without creating a request or consuming anything. Runs the exact same matching logic POST /approvals uses, so the verdict here and a real submission's can never disagree. Fails closed: mandates disabled, an unknown action, or an internal error all answer covered: false with a reason in a 200, never a false positive.
Register, update, disable, remove and rotate the secret of the endpoints DueReason delivers approval.* and decision.* events to; inspect and redeliver past deliveries, or send a test event. See Webhooks below for the payload, headers and verifying signatures.
GET/api/v1/webhooks
List webhook endpoints
Your organization's webhook endpoints, newest first. Never includes the signing secret; it is shown only once, in the create response (or the console, on rotation).
Scope
webhook:manage
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/webhooks" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/webhooks/{id}
Get a webhook endpoint
One webhook endpoint by id: its url, subscribed events, active flag and signing-secret rotation state. Never includes the signing secret itself; it is shown only once, in the create response (or the console, on rotation).
curl -X GET "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks
Create a webhook endpoint
Registers an HTTPS endpoint and the events it receives. The signing secret (whsec_...) is in this response only; store it immediately, you cannot read it again.
Toggles active or replaces the subscribed event list (events, when given, replaces it whole; omit either field to leave it unchanged). A disabled endpoint receives no new deliveries; already-queued ones keep waiting until you re-enable it or redeliver them.
Issues a new signing secret immediately. Deliveries queued before this call were already signed with the old secret; everything sent after uses the new one right away. The secret this rotation replaced is in this response and, for 24h, readable once more in the console while you roll your receiver's verification over; after that it is gone for good.
Delivery attempts for one endpoint, newest first, including pending and failed ones. Optionally filter by status or eventType. limit defaults to 50 and is capped at 200.
curl -X GET "https://www.duereason.com/api/v1/webhooks/whk_0192a714f6a87b9c0d1e2f3a4b5c6d7e/deliveries?limit=20" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/webhooks/{id}/test
Send a test event
Queues a synthetic test delivery through the same pipeline as a real event (signing, SSRF checks, retries), so you can confirm the URL, secret and signature verification before a real event fires. 412 precondition_failed on a disabled endpoint.
Queues the delivery again with a fresh retry budget, keeping its id and payload so your receiver can deduplicate on the DueReason-Delivery header. 412 precondition_failed while the endpoint is disabled.
These endpoints answer 412 precondition_failed until an organization owner turns the platform-work module on in Settings.
Decisions
Record decisions and follow them through the human gate: enact, withdraw, explain in writing and relay review requests.
POST/api/v1/decisions
Create a decision
Records a decision about a person in the ledger. Restrict, suspend and terminate start as pending_human and wait for a trained reviewer (Art. 10(5)); every other type is recorded immediately. An unknown workerRef is registered on the fly when workerCountry is given. Automated decisions must cite an active system by systemKey.
curl -X POST "https://www.duereason.com/api/v1/decisions" \
-H "Authorization: Bearer $DUEREASON_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"workerRef": "courier-4821",
"workerCountry": "PL",
"systemKey": "fraud-score",
"type": "suspend",
"automatedDetection": true,
"automatedDecision": false,
"summary": "Account suspended for 7 days in all delivery zones.",
"facts": "Five deliveries on 28 September were confirmed 3 km or more from the drop-off point, according to the GPS trace.",
"contractualGround": "Terms of service, section 8.2 (accurate delivery confirmation).",
"durationDays": 7,
"externalRef": "case-2026-0931"
}'
GET/api/v1/decisions
List decisions
Decisions in your organization, newest first, optionally filtered by status or by person.
Scope
decision:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/decisions?status=pending_human&limit=20" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/decisions/{id}
Get a decision
One decision with its statement of reasons, if issued, and its open review request, if any. Keys with the statement:issue scope also receive the worker portal link.
curl -X GET "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
POST/api/v1/decisions/{id}/enact
Enact a decision
Confirms that you have acted on an approved or recorded decision. A decision still pending_human returns 409: enact only after the decision.approved webhook.
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/withdraw" \
-H "Authorization: Bearer $DUEREASON_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"reason": "Raised twice by the fraud pipeline; case-2026-0930 stands."
}'
POST/api/v1/decisions/{id}/statement
Issue the statement of reasons
Freezes the written statement of reasons (Art. 11(1); DSA Art. 17) for a decision in effect and returns a signed portal link for the person. If the worker has a contact email, DueReason also emails the link. Fails with 422 when the decision lacks the facts, a ground or a contact person.
Records that the person asked for a review through your own interface (Art. 11(2)). The two-week deadline starts now; one review may be open per decision.
curl -X POST "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/review-requests" \
-H "Authorization: Bearer $DUEREASON_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"comment": "The app froze and confirmed the wrong stop."
}'
Workers
Pseudonymous records of the people decisions are about.
PUT/api/v1/workers/{externalRef}
Create or update a worker
Creates the person under your pseudonymous reference, or updates the fields you send. Repeating the same request leaves the record unchanged. Erased workers return 409.
curl -X GET "https://www.duereason.com/api/v1/decisions/dec_0192a6c4e1f37b9d8c2e4f6a8b0c1d2e/events" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/ledger/head
Get the ledger head
The latest position and hash of your organization's platform-work decision chain and the result of its last full verification. Store the head in a system you control: a later head that does not extend it means the chain was rewritten.
Scope
decision:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/ledger/head" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
GET/api/v1/ledger/approvals/head
Get the approval ledger head
The latest position and hash of your organization's approval chain (every requested, answered, approved, executed and cancelled event) and the result of its last full verification. Store the head in a system you control: a later head that does not extend it means the chain was rewritten.
Scope
approval:read
Success
200
Example
curl -X GET "https://www.duereason.com/api/v1/ledger/approvals/head" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
Notices
DSA add-on: notices of illegal content under Art. 16 of Regulation (EU) 2022/2065. While the add-on is off, these endpoints answer 412 with the code precondition_failed.
POST/api/v1/notices
Relay a notice
Records a notice of allegedly illegal content that a person sent through your own interface (Art. 16(1)). The notice must carry what Art. 16(2) requires: the location of the content, a substantiated explanation, the notifier's name and email (unless csamExemption is true for child sexual abuse material, with the category STATEMENT_CATEGORY_PROTECTION_OF_MINORS) and the good-faith statement. A notice that falls short is a 422 whose details.problems names each gap. When an email address is given, DueReason emails the confirmation of receipt (Art. 16(4)) in the notice's language, and later the decision with the redress options (Art. 16(5)). Notices are decided by people in the console.
curl -X POST "https://www.duereason.com/api/v1/notices" \
-H "Authorization: Bearer $DUEREASON_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"contentUrls": [
"https://example-platform.eu/listings/88213"
],
"contentDescription": "Listing titled '\''Original designer handbag, new'\''.",
"explanation": "The handbag is a counterfeit of a registered EU trade mark: the logo and serial number do not match the manufacturer'\''s.",
"category": "STATEMENT_CATEGORY_INTELLECTUAL_PROPERTY_INFRINGEMENTS",
"notifierName": "Anna Kowalska",
"notifierEmail": "anna.kowalska@example.com",
"goodFaith": true,
"locale": "pl"
}'
GET/api/v1/notices/{id}
Get a notice
One notice with its status, the decision once taken, the ledger decision about the affected person if one is linked (its statement of reasons is the Art. 17 statement), and when the confirmation and the decision were emailed to the notifier.
curl -X GET "https://www.duereason.com/api/v1/notices/ntc_0192a6d2b7c84e1f9a3b5c7d9e1f3a5b" \
-H "Authorization: Bearer $DUEREASON_API_KEY"
Webhooks
Owners and admins add endpoints under Settings, Webhooks and choose the events they receive, or * for all of them. Each event is POSTed as JSON to your HTTPS endpoint. The signing secret (whsec_...) is shown once when the endpoint is created or its secret is rotated.
An endpoint subscribed to an explicit list of events never automatically starts receiving an event type added to the product later; its list has to be updated to add the new type. Choose * instead to subscribe to every current and future event type without updating the endpoint again.
The body has id (the ledger event id), type, createdAt and data. For approval.* events, data always carries requestId and seq; for decision.* events (platform-work module), data carries decisionId and seq instead; plus the fields of that event.
{
"id": "evt_0192a7a1b2c3d4e5f6a7b8c9d0e1f2a4",
"type": "decision.review_reversed",
"createdAt": "2026-10-05T14:22:47.512Z",
"data": {
"decisionId": "dec_0192a76e1f2a3b4c5d6e7f8a9b0c1d2e",
"seq": 6,
"reviewId": "rev_0192a7901a2b3c4d5e6f7a8b9c0d1e2f",
"resolution": "Lowered-ranking penalty did not account for the worker's active appeal window; reversed.",
"onTime": true
}
}
Headers
Header
Value
DueReason-Event
The event type, e.g. decision.approved.
DueReason-Delivery
Delivery id. Retries and manual redeliveries reuse it: deduplicate on it.
DueReason-Signature
Two comma-separated parts: t, the Unix time of signing, and v1, the hex HMAC-SHA256 of t, a dot and the raw body, keyed with your secret.
User-Agent
DueReason-Webhooks/1
Events
* subscribes an endpoint to every current and future event type, approval.* and decision.* alike; it is never itself a delivered type. The console's "Send test event" sends the synthetic test event instead, with the same envelope shape as whichever real event it mimics -- type is never test for a real delivery, and test is never subscribable.
The person asked for a review; the two-week clock started.
decisionId, reviewId, channel, dueAt
decision.review_upheld
The review confirmed the decision.
decisionId, reviewId, resolution, onTime
decision.review_reversed
The review reversed the decision. Undo the measure and record the remedy.
decisionId, reviewId, resolution, onTime
decision.remedied
The decision was rectified or compensated after a reversal.
decisionId, reviewId, remedy, note
Verifying signatures
Verify it with @duereason/sdk's verifyWebhookSignature instead of computing the HMAC-SHA256 yourself: pass your endpoint secret, the raw request body and the header, and it checks the signature in constant time and rejects timestamps more than five minutes old to stop replays.
Node.js
import { verifyWebhookSignature } from "@duereason/sdk";
import express from "express";
const app = express();
// Keep the raw bytes: a re-serialized object would not match the signature.
app.post("/webhooks/duereason", express.raw({ type: "application/json" }), (req, res) => {
const body = req.body.toString("utf8");
const header = req.get("DueReason-Signature") ?? "";
if (!verifyWebhookSignature(process.env.DUEREASON_WEBHOOK_SECRET, body, header)) {
return res.status(400).end();
}
const event = JSON.parse(body);
// Retries reuse DueReason-Delivery: skip ids you have already handled.
if (event.type === "approval.approved") {
// Now, and only now, run the business logic this request gated.
}
res.status(204).end();
});
Next.js (App Router)
// app/api/webhooks/duereason/route.ts
import { verifyWebhookSignature } from "@duereason/sdk";
export async function POST(request: Request) {
const body = await request.text(); // raw bytes -- do not call request.json() first
const header = request.headers.get("DueReason-Signature") ?? "";
if (!verifyWebhookSignature(process.env.DUEREASON_WEBHOOK_SECRET!, body, header)) {
return new Response(null, { status: 400 });
}
const event = JSON.parse(body);
// Retries reuse DueReason-Delivery: skip ids you have already handled.
if (event.type === "approval.approved") {
// Now, and only now, run the business logic this request gated.
}
return new Response(null, { status: 204 });
}
Not on Node? A tested Python port of verifyWebhookSignature -- same header parsing, tolerance window and constant-time compare, stdlib only -- ships in the SDK's source tree as duereason/sdk/examples/python/verify_webhook_signature.py, next to the Python grant-verification example.
Delivery and retries
Any 2xx response within 10 seconds counts as delivered. Anything else is retried up to 8 attempts in total, waiting 30 seconds after the first failure and doubling each time, at most 6 hours apart. Redirects are not followed. After the last attempt the delivery is marked failed; you can redeliver it from the console.
A non-2xx status is retried the same way as a timeout or connection error -- 4xx responses included, unlike many other webhook providers that give up after a 4xx. The only failure that stops retrying immediately, without working through the full schedule, is the endpoint's signing secret failing to decrypt; everything else, including a URL that now fails outbound validation, keeps retrying on the schedule above.
Handle the request asynchronously and return a 2xx within the 10-second timeout: a handler that blocks past it looks identical to a dead endpoint, triggers a retry, and can end up delivering the same event twice once the slow response finally arrives. DueReason-Delivery stays the same across every retry of one logical delivery, so dedupe on it regardless of how many attempts it took.
After 5 consecutive deliveries to an endpoint exhaust their retries, the organization's owners and admins get one email about it -- not one per attempt -- linking to Settings > Webhooks; a successful delivery resets the counter immediately.
Inbound: GitHub issues and pull requests
The webhooks above are DueReason telling your systems about an approval. The other direction also exists: a labeled GitHub issue or pull request can open a DueReason approval request automatically. Add an endpoint under Settings > Integrations > Inbound webhooks, then paste the webhook URL and your own secret into the repository's GitHub webhook settings (content type application/json). DueReason verifies GitHub's HMAC-SHA256 signature over the raw body before acting, and a retried delivery (same X-GitHub-Delivery id) never opens a second request.
Configure inbound endpoints in Settings > Integrations > Inbound webhooks.
Self-hosting
Prefer to run DueReason yourself? One Postgres database and one Docker image (web, worker and migrator) get a working instance up in three commands, no build step.
Self-hosted deployments run under the Elastic License 2.0: you may run, read and modify the code, but not offer it to others as a hosted or managed service, or circumvent its license-key functionality.