Request a reveal grant

POST /v1/reveal-grants

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

Requests a time-boxed right to read named content classes of named Calls, or of one Agent's Calls in a window (1.57.0). Under the Compliance profile's reveal_approval: none the grant is active at once and emits content.reveal_granted; under required it is pending until another owner or auditor approves it. A class the requester's role is denied is refused with validation_failed and the issue class_not_revealable; a Call of another Organization is not found; a grant for vocal_support by a Member who is not an owner is forbidden with the detail owner_required.

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" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "classes": [
      "transcripts"
    ],
    "reason": "<reason>"
  }'

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

import os
import uuid

import requests

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

Parameters

Name	In	Type	Required	Description
`idempotency-key`	header	string	yes	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: RevealGrantCreateRequest.

Field	Type	Required	Description
`agent_id`	AgentId	no	One Agent's Calls, with `window_from` and `window_to`; instead of `call_ids`.
`call_ids`	array of CallId	no	Up to 20 Calls (a target), each once.
`classes`	array of ContentLogClass	yes	The content classes the grant reveals, each once.
`duration_minutes`	integer	no	How long the grant stays active once active: 60 minutes when absent, at most 240 (targets).
`grantee`	RevealGrantee	no
`reason`	string	yes	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`.
`window_from`	RequestTimestamp	no	The start of the window of the Agent scope: Calls created at or after it.
`window_to`	RequestTimestamp	no	The end of the window: Calls created before it; at most 24 hours (a target) after `window_from`.

Responses

Status	Content type	Shape	Error codes
`201`	`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	`idempotency_in_progress`, `idempotency_key_reused`
`422`	`application/json`	ErrorEnvelope	`validation_failed`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `201` 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