For AI agents: markdown of this page — /docs-content-en/infra/access/audience-proposals.md documentation index — /llms.txt

Check or cancel an audience request

GET /v1/infra/servers/:id/audience-proposals/:proposalId

POST /v1/infra/servers/:id/audience-proposals/:proposalId/cancel

Let the original API key read or cancel its own request to change application access. The original operation returns proposalId in error.details.proposalId with 409 AUDIENCE_APPROVAL_REQUIRED. Another key belonging to the same owner cannot access the request.

An API key cannot approve a request. A signed-in person makes that decision in their account. APPROVED means consent has been given, not that the change has been applied: retry the original operation with the same key, exact parameters and approvalId. Cancellation itself does not change access.

Parameters

Parameter In Type Required Description
Parameterid Inpath Typestring (UUID) Requiredyes DescriptionServer ID from the original operation; see List servers
ParameterproposalId Inpath Typestring (UUID) Requiredyes DescriptionRequest ID from error.details.proposalId

The cancellation body is optional. If provided, it must be an empty object {}. The verified X-Api-Key identifies the caller; body fields cannot supply an identity.

Examples

curl — check

Terminal 
curl "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/audience-proposals/PROPOSAL_ID"   -H "X-Api-Key: YOUR_API_KEY"

curl — cancel

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/audience-proposals/PROPOSAL_ID/cancel"   -H "X-Api-Key: YOUR_API_KEY"

JavaScript — check

javascript 
const response = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/audience-proposals/${proposalId}`,
  { headers: { 'X-Api-Key': apiKey } },
)
const { proposal } = await response.json()
console.log(proposal.state)

JavaScript — cancel

javascript 
const response = await fetch(
  `https://vibecode.bitrix24.com/v1/infra/servers/${serverId}/audience-proposals/${proposalId}/cancel`,
  { method: 'POST', headers: { 'X-Api-Key': apiKey } },
)
const { proposal } = await response.json()
console.log(proposal.state)

Response fields

A successful response is { "proposal": ... }, without a success or data envelope. The table lists the main fields; the response also includes the exact operation, original, proposed and current access snapshots, participant labels and differences.

Field Type Description
Fieldproposal.id Typestring (UUID) DescriptionRequest ID
Fieldproposal.state Typestring DescriptionPENDING, APPROVED, APPLIED, REJECTED, CANCELLED, EXPIRED or STALE
Fieldproposal.baseRevision Typestring DescriptionAccess revision when the request was created; a decimal string
Fieldproposal.currentRevision Typestring DescriptionCurrent access revision; a decimal string
Fieldproposal.expiresAt Typestring DescriptionRequest expiry in ISO 8601
Fieldproposal.canDecide Typeboolean DescriptionAlways false for an API key
Fieldproposal.canCancel Typeboolean DescriptionWhether the request can be cancelled now
Fieldproposal.resultEntityId Typestring (UUID), optional DescriptionID of the record created when applied; not a token or secret URL

Response example

Only the ID, state and revisions from the status response are shown below:

JSON 
{
  "proposal": {
    "id": "00000000-0000-4000-8000-000000000001",
    "state": "PENDING",
    "baseRevision": "0",
    "currentRevision": "0"
  }
}

Successful cancellation returns the CANCELLED state.

Error response example

404 — the request does not exist or belongs to another caller:

JSON 
{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "Proposal not found" }
}

Errors

HTTP Code Description
HTTP400 CodeVALIDATION_ERROR DescriptionInvalid UUID or a nonempty cancellation body
HTTP401 CodeMISSING_API_KEY DescriptionNo key was supplied
HTTP401 CodeINVALID_API_KEY DescriptionThe key was not recognized
HTTP403 CodeAUDIENCE_APPROVAL_FORBIDDEN DescriptionThe current key, its owner or portal binding no longer permits the operation
HTTP404 CodeNOT_FOUND DescriptionNo server or request in the required portal, or the request was created by another caller
HTTP409 CodeAUDIENCE_APPROVAL_REPLAY DescriptionCancellation: the request was already applied, cancelled or completed by another decision
HTTP409 CodeAUDIENCE_APPROVAL_STALE DescriptionCancellation: the access revision changed
HTTP410 CodeAUDIENCE_APPROVAL_EXPIRED DescriptionCancellation: the request expired

For common API errors, see Errors.

Known specifics

  • The original key is still required. Issuing another key to the same owner does not transfer the request. Even a key with the vibe:cowork scope can check and cancel its own request if the other current checks pass; this does not authorize it to perform infra write operations.
  • Reading detects an outdated request. A status check may return STALE or EXPIRED. That consent cannot be used; create a new request through the original operation.
  • The report does not return secrets. Only the original operation receives Bearer/JWT credentials or secret URLs after application, not these methods.

See also