Skip to the content

Revoke a reveal grant

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

Property	Value
Operation	`revoke_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.revoke` (mutation)
Released in	1.57.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Ends a pending or active grant at once (1.57.0), by its requester or an owner, any other Member being forbidden with the detail requester_or_owner_required; reads under it stop. A grant that is declined, expired or revoked answers 409 reveal_grant_conflict with the reason not_revocable.

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_.../revoke" \
  -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_.../revoke`, {
  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_.../revoke",
    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