Skip to the content

Approve a pending reveal grant

POST /v1/reveal-grants/{reveal_grant_id}/approve

Property	Value
Operation	`approve_reveal_grant`
Group	Capture windows and reveal grants
Scope	`reveal_grants:write`
Route class	`control`
Idempotency	`Idempotency-Key` accepted: a retry with the same key replays the first answer
Audit	Audited `reveal_grant.approve` (mutation)
Released in	1.57.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Makes a pending grant active for its duration and emits content.reveal_granted (1.57.0). Only an owner or auditor other than the requester decides (403 forbidden, detail approver_role_required or approver_is_requester); a grant that is no longer pending answers 409 reveal_grant_conflict with the reason not_pending.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the reveal_grants:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/reveal-grants/rvg_.../approve" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch(`${process.env.VOCAL_API}/v1/reveal-grants/rvg_.../approve`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/reveal-grants/rvg_.../approve",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={},
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`reveal_grant_id`	path	RevealGrantId	yes	The id of a reveal grant, a time-boxed right to read named content classes of named Calls: `rvg_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.
`idempotency-key`	header	string	no	A client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: RevealGrantDecisionRequest.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	RevealGrant
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`, `org_suspended`
`404`	`application/json`	ErrorEnvelope	`not_found`
`409`	`application/json`	ErrorEnvelope	`reveal_grant_conflict`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is RevealGrant.

Field	Type	Required	Description
`agent_id`	AgentId or null	yes
`approval_required`	boolean	yes	True when the profile required a second approver at the request.
`call_ids`	array or null	yes	The named Calls; null for an Agent scope.
`classes`	array of ContentLogClass	yes
`created_at`	Timestamp	yes
`decided_at`	Timestamp or null	yes
`decided_by`	MemberId or null	yes	The approver or decliner; null under `reveal_approval: none`.
`duration_minutes`	integer	yes
`expires_at`	Timestamp or null	yes	When an active grant ends; for a pending grant, when the request lapses.
`grantee`	RevealGrantee	yes
`id`	RevealGrantId	yes
`object`	`"reveal_grant"`	yes
`reason`	string or null	no	Why the content is needed, for the access review: free text that can quote a caller, stored as a content pair and scrubbed at `retention_days`. Answered only by GET `/v1/reveal-grants/{reveal_grant_id}`, an audited content read; null once scrubbed.
`requested_by`	MemberId	yes
`revoked_at`	Timestamp or null	yes
`revoked_by`	MemberId or null	yes
`starts_at`	Timestamp or null	yes	When the grant became active; null until then.
`status`	RevealGrantStatus	yes
`window_from`	Timestamp or null	yes
`window_to`	Timestamp or null	yes