> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Independent agent reviews

> Request human review, collect distinct decisions, and enforce the final outcome in your application.

Agent approvals record human decisions about a proposed agent action in one workspace environment. They are separate from workflow-engine approvals, permission grants, cryptographic action receipts, and Temporal execution.

## Before you start

* Use an active agent from the same workspace and environment as your credential.
* Create requests using a workspace API key or a signed-in workspace user.
* Reviewers must be active human workspace members with the workspace-level `tenant:governance:approve` permission. An organization-only role is insufficient.
* The requester cannot approve or reject their own request. Each reviewer may decide once. API keys cannot cast human votes.

In Console, open **AI Agents → Agent Approvals**. The request, review, and cancellation forms each have a dedicated page. Save the request link to return to it after it leaves the pending queue.

## Create a request

This example requests two independent approvals in a one-hour window. Replace the agent identifier with an existing sandbox agent; a production agent cannot be used with a sandbox credential.

```bash theme={null}
curl --fail-with-body https://sandbox-api.truthlocks.com/v1/approvals \
  -H "X-API-Key: $TRUTHLOCKS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "agent_id": "YOUR_SANDBOX_AGENT_ID",
    "action": "publish reviewed report",
    "resource": "reports/quarterly-review",
    "scope": "reports:publish",
    "risk_level": "high",
    "justification": "The report has completed technical review. Confirm the approved version before publication.",
    "required_approvals": 2,
    "ttl_minutes": 60
  }'
```

The `201` response contains `id`, `requested_by`, `status: "pending"`, `current_approvals: 0`, and `expires_at`. Save `id`; creation does not publish the report or create a background workflow.

## Review with a human session

Use Console for interactive decisions. If your integration uses the API, supply the reviewer's short-lived workspace bearer session. Do not substitute an API key or embed a session token in source code.

```bash theme={null}
curl --fail-with-body "https://sandbox-api.truthlocks.com/v1/approvals/$APPROVAL_ID/approve" \
  -H "Authorization: Bearer $TRUTHLOCKS_REVIEWER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Reviewed the exact report version and its supporting evidence."}'
```

The first approval in this example returns `status: "pending"` and `current_approvals: 1`. A different authorized reviewer must supply the second vote. Reusing the same reviewer returns a conflict. One rejection immediately changes the request to `rejected` regardless of earlier approvals.

The service verifies current membership permissions, request ownership, expiry, and existing votes inside the decision transaction. Votes and the audit event commit together. Decisions cannot be edited or deleted through these APIs.

## Check and enforce the outcome

```bash theme={null}
curl --fail-with-body "https://sandbox-api.truthlocks.com/v1/approvals/$APPROVAL_ID" \
  -H "X-API-Key: $TRUTHLOCKS_API_KEY"
```

The detail response includes the reviewer history. Only proceed when `status` is `approved` and the request still matches the exact agent, action, resource, and scope your application intends to use. Your application must also enforce current access permissions, agent status, and its own single-use or replay controls. These approval records do not provide an automatic execution or consumption mechanism.

| Status | Meaning |
| - | - |
| `pending` | More independent approvals are required. |
| `approved` | The configured quorum was reached within the review window. |
| `rejected` | An independent reviewer rejected the request. |
| `expired` | A pending request passed its review deadline. |
| `cancelled` | Its original requester cancelled it. |

The review deadline limits when decisions can be submitted. It does not turn an already approved request into an expiring access token. Define any execution deadline in your own application.

## Queue, cancellation, and errors

`GET /v1/approvals` returns an array of at most 100 oldest pending, unexpired requests. It has no pagination or historical-status filter. The queue omits individual decision history; fetch a request by ID for that history.

The original requester can send `POST /v1/approvals/{approvalID}/cancel` with a nonblank `reason`. A request cannot be reopened after cancellation, rejection, approval, or expiry. Create a new request if the proposed action changes.

| HTTP status | What to check |
| - | - |
| `400` | Field limits, a UUID request ID, and a nonblank decision reason. |
| `403` | Current workspace reviewer permission, requester self-review, API-key voting, or cancellation ownership. |
| `404` | Request or active agent belongs to the selected workspace environment. |
| `409` | Request is final, expired, or this person already voted. |

These records support your review process; they do not establish SOC 2 compliance, ISO certification, identity-document verification, or the correctness of submitted evidence.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.