Skip to the content

Read a reveal grant with its reason

GET /v1/reveal-grants/{reveal_grant_id}

Property	Value
Operation	`get_reveal_grant`
Group	Capture windows and reveal grants
Scope	`reveal_grants:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	An audited content read `reveal_grant.read`
Released in	1.57.0
Phase 0 host	Served (the hosted api pins 1.65.0)

One reveal grant with its reason, an audited content read (1.57.0), for its requester, an owner or an auditor; the reason is null once scrubbed.

Request

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

curl "$VOCAL_API/v1/reveal-grants/rvg_..." \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/reveal-grants/rvg_...`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/reveal-grants/rvg_...",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
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.

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`
`404`	`application/json`	ErrorEnvelope	`not_found`
`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