API reference

Every endpoint of the HTTP API, who may call it, and the OpenAPI document to generate a client from.

The API is plain JSON over HTTPS at https://api.variantgate.com. Agents use a handful of endpoints to ask and read answers; the app uses the rest, and so can your own tools when they act as a signed-in person.

The OpenAPI document

The full description, with every field and response, is at /openapi.json (OpenAPI 3.1). It is generated from the API’s own code, so it cannot drift from what the API does. Generate a typed client from it:

# TypeScript types
npx openapi-typescript https://variantgate.com/openapi.json -o approvals.d.ts

# A Python client
pipx run openapi-python-client generate --url https://variantgate.com/openapi.json

Authentication

Every call sends Authorization: Bearer <token>, except the health checks, GET /v1/billing, the Enterprise inquiry form and the emailed decision links, which carry their own secret. Which token decides what the caller may do:

Agent key
Starts with gl_. Created under Agents, one per agent. Can ask, and read, withdraw and report on its own requests. Cannot see another key's requests, list or decide requests, or change anything.
Person
The short-lived token a person gets from signing in. Can read the inbox, decide, and, as an owner, manage keys, rules and people.

An agent key on a person’s endpoint gets 403 forbidden, so an agent can never decide its own request. See Security.

Conventions

Errors
Always { error: { code, message } }. Match on code.
x-request-id
Sent back with every response. Quote it when reporting a problem.
wait_seconds
On asking and reading: hold the call open up to 30 seconds for a decision.
Times
RFC 3339, in UTC.
Amounts
Strings such as "129.00" are read exactly; numbers are accepted too.

Error codes and rate limits are on Limits and errors; the fields of a request on Requests.

Endpoints

What an agent calls

POST/v1/requests

Asks a person to approve an action.

Agent key

GET/v1/requests/{request_id}

Reads a request's current state. Act only when `allowed` is true. Pass `wait_seconds` to wait for the answer instead of calling again and again.

Agent key

POST/v1/requests/{request_id}/outcome

Says how an approved action went, so the record shows not only that it was allowed but whether it was done. Reported once, by the key that asked.

Agent key

POST/v1/requests/{request_id}/withdraw

Takes back a request nobody has decided yet: the plan changed, or the agent no longer needs it. Only the key that asked may do this.

Agent key

The signed-in person and their workspaces

GET/v1/me

Who is signed in, and which workspaces they can open.

Signed-in person

DELETE/v1/me

Deletes the signed-in person's account for good. Workspaces nobody else is in are deleted, as `DELETE /v1/workspaces/{id}` does, plan included. Shared workspaces are left: the person's push devices, email settings, weekly summaries and unused join links there go, while their past decisions and changes stay in those workspaces' sealed records. Refused while they are the only owner of a workspace with other people in it. Their sign-in is deleted last.

Signed-in person

GET/v1/push

Says whether push notifications are on, and the key to subscribe with.

Signed-in person

POST/v1/weekly-summary/unsubscribe

Turns off the weekly summary an emailed link was sent for: one person's, of one workspace. Using a link twice changes nothing more. They can turn it back on under Settings.

Anyone

POST/v1/workspaces

Creates a workspace owned by the caller.

Signed-in person

DELETE/v1/workspaces/{workspace_id}

Deletes the workspace and everything in it for good: requests and their decisions, the sealed record and activity log, rules, agent keys, invitations and settings. Everyone in it loses access. Only owners may do this. A paid plan is cancelled with Stripe first, with a final invoice for what was used and not billed yet; if Stripe cannot do that, nothing is deleted.

Signed-in person

PUT/v1/workspaces/{workspace_id}/email-preference

Turns your own emails about this workspace on or off: about waiting requests, and the weekly summary. Give at least one. Every member chooses for themself; nobody can change it for someone else.

Signed-in person

PUT/v1/workspaces/{workspace_id}/name

Gives the workspace a new name, which everyone in it sees. The change is kept in the activity log. Only workspace owners may do this.

Signed-in person

PUT/v1/workspaces/{workspace_id}/notifications

Announces every request that needs a person in a chat channel: Slack, Microsoft Teams or Discord. The webhook replaces any set before, so a workspace announces in one place. It is stored but never shown again. Only workspace owners may set this.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/notifications

Stops announcing requests and forgets the webhook.

Signed-in person

PUT/v1/workspaces/{workspace_id}/pause

Stops every agent in the workspace at once. Any member may do this, because stopping is always the safe direction.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/pause

Lets agents act again on what was approved. Only workspace owners may do this.

Signed-in person

GET/v1/workspaces/{workspace_id}/push-devices

Lists the browsers that get your push notifications from this workspace.

Signed-in person

POST/v1/workspaces/{workspace_id}/push-devices

Sends your push notifications for this workspace to this browser. Subscribing the same browser again only refreshes it.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/push-devices/{device_id}

Stops sending your push notifications for this workspace to a browser.

Signed-in person

GET/v1/workspaces/{workspace_id}/usage

Shows the workspace's plan and this month's usage.

Signed-in person

Requests waiting for, or holding, a decision

POST/v1/decision-links/decide

Records the decision an emailed link is for, in the name of the member it was sent to, exactly as the inbox would. The link is used up, and so is that member's other link for the request.

Anyone

POST/v1/decision-links/view

Shows the request an emailed link is for, and what it would record. Decides nothing.

Anyone

GET/v1/workspaces/{workspace_id}/record/entries

Lists the entries of the workspace's sealed record, oldest first, so anyone can recompute the chain without trusting this server.

Signed-in person

GET/v1/workspaces/{workspace_id}/record/verify

Recomputes the workspace's record chain from its first entry to its latest, and says whether it is intact.

Signed-in person

GET/v1/workspaces/{workspace_id}/requests

Lists a workspace's requests, newest first.

Signed-in person

GET/v1/workspaces/{workspace_id}/requests/export

Downloads what was decided or expired, newest first, as CSV.

Signed-in person

GET/v1/workspaces/{workspace_id}/requests/{request_id}

Shows one request.

Signed-in person

POST/v1/workspaces/{workspace_id}/requests/{request_id}/decision

Approves or denies a pending request. A decision is final.

Signed-in person

GET/v1/workspaces/{workspace_id}/stats

Shows what happened in the workspace over the last 30 days.

Signed-in person

Keys that let agents ask for approval

GET/v1/workspaces/{workspace_id}/agent-keys

Lists a workspace's agent keys, newest first.

Signed-in person

POST/v1/workspaces/{workspace_id}/agent-keys

Creates an agent key. Only workspace owners may do this.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/agent-keys/{key_id}

Revokes an agent key at once. Only workspace owners may do this.

Signed-in person

PUT/v1/workspaces/{workspace_id}/agent-keys/{key_id}/pause

Pauses one agent key. Until it is resumed, nothing that agent asks for is allowed, whatever was approved, and no rule approves it. Any member may do this.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/agent-keys/{key_id}/pause

Lets a paused agent act again on what was approved. Only owners may.

Signed-in person

PUT/v1/workspaces/{workspace_id}/agent-keys/{key_id}/scope

Sets which actions an agent key may ask for. Takes effect on the key's next request. Only workspace owners may do this.

Signed-in person

GET/v1/workspaces/{workspace_id}/agents/report

Shows, per agent key, what it asked for over the period and how that went.

Signed-in person

Who is in a workspace, and inviting more

POST/v1/invitations/accept

Joins the workspace an invitation is for. The invitation is used up.

Signed-in person

GET/v1/workspaces/{workspace_id}/invitations

Lists the invitations that can still be used. Only owners may see them.

Signed-in person

POST/v1/workspaces/{workspace_id}/invitations

Creates an invitation. Only workspace owners may do this.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/invitations/{invitation_id}

Withdraws an invitation, so its link stops working.

Signed-in person

GET/v1/workspaces/{workspace_id}/members

Lists the people in a workspace, in the order they joined.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/members/{user_id}

Removes a person from a workspace. An owner may remove anyone; anyone may remove themselves. The last owner cannot be removed.

Signed-in person

PUT/v1/workspaces/{workspace_id}/members/{user_id}/role

Makes someone an owner or a member. Only owners may do this, themselves included, and the last owner cannot be made a member. The change is kept in the activity log; giving someone the role they have changes nothing.

Signed-in person

Who changed what in a workspace: keys, rules, people, settings and plan

GET/v1/workspaces/{workspace_id}/activity

Lists who changed what in the workspace, newest first: agent keys, rules, the pause, people, invitations, notifications, webhooks and the plan.

Signed-in person

GET/v1/workspaces/{workspace_id}/activity/export

Downloads the activity log as CSV, newest first: one change per line, with its place in the sealed record and its hash.

Signed-in person

Answers given in advance: allow, deny or always ask

GET/v1/workspaces/{workspace_id}/rules

Lists a workspace's rules, oldest first.

Signed-in person

POST/v1/workspaces/{workspace_id}/rules

Writes a rule. Only workspace owners may do this, because an `allow` rule approves requests in advance in the owner's name.

Signed-in person

POST/v1/workspaces/{workspace_id}/rules/test

Shows what a request would get right now, and why: allowed or denied at once, refused, or waiting for a person, with the rules that match. Nothing is stored, nobody is told, and nothing counts toward the plan.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/rules/{rule_id}

Removes a rule. Requests it already decided stay decided.

Signed-in person

How approvals are going, and rules worth writing

GET/v1/workspaces/{workspace_id}/insights

Shows how approvals went over the period and the one before it: how requests ended, how fast people decided, per action, per person and per currency. Owners also get the rules worth writing.

Signed-in person

POST/v1/workspaces/{workspace_id}/insights/dismissals

Hides the rule suggestion for one agent key and action, for every owner of the workspace. Only owners, who see suggestions, may.

Signed-in person

Signed events about requests, sent to your own systems

GET/v1/workspaces/{workspace_id}/webhooks

Lists a workspace's webhooks, oldest first. Every member may look.

Signed-in person

POST/v1/workspaces/{workspace_id}/webhooks

Adds a webhook and returns its signing secret, once. Only owners may add one, a workspace has at most five, and it needs the Pro plan or higher.

Signed-in person

DELETE/v1/workspaces/{workspace_id}/webhooks/{webhook_id}

Removes a webhook. Nothing more is sent to it, including what was still waiting to be tried again. Only owners may do this.

Signed-in person

GET/v1/workspaces/{workspace_id}/webhooks/{webhook_id}/deliveries

The webhook's latest 50 deliveries, newest first. Every member may look.

Signed-in person

PUT/v1/workspaces/{workspace_id}/webhooks/{webhook_id}/enabled

Turns a webhook off or on. Only owners may do this.

Signed-in person

POST/v1/workspaces/{workspace_id}/webhooks/{webhook_id}/secret

Replaces a webhook's signing secret and returns the new one, once. Only owners may do this.

Signed-in person

POST/v1/workspaces/{workspace_id}/webhooks/{webhook_id}/test

Queues a `webhook.test` event for one webhook, whatever events it asked for. It is sent like any other, within seconds. Only owners may do this.

Signed-in person

Paying for a plan

GET/v1/billing

Says whether plans can be bought on this server. Anyone may ask.

Anyone

GET/v1/workspaces/{workspace_id}/billing

Shows a workspace's plan and how it is paid for.

Signed-in person

POST/v1/workspaces/{workspace_id}/billing/checkout

Starts paying for a plan. Returns a Stripe Checkout page to send the person to. Only owners may do this, and only while the workspace has no subscription; an existing one is changed in the billing portal. While a checkout is open, asking again for the same plan gives the same page, and asking for another plan, or another way of paying, closes the open one first. Team and Business can be paid per request: no seats, a monthly bill for the requests agents made, and a monthly request cap.

Signed-in person

POST/v1/workspaces/{workspace_id}/billing/portal

Opens Stripe's billing portal, where an owner changes or ends the plan, updates the card and downloads invoices.

Signed-in person

PUT/v1/workspaces/{workspace_id}/request-cap

Sets the most requests a month the workspace takes while it pays per request. Past it, agents are told they are not allowed until the next month or a higher cap. The cap is kept when the workspace pays another way, and applies again if it goes back to paying per request. Only owners may do this; the change is logged.

Signed-in person

Writing to the team about Enterprise

POST/v1/inquiries

Sends an Enterprise inquiry to the team. Anyone may call this. Answers 202 once it is sent, and also, without sending anything, when the hidden `website` field is filled in.

Anyone

Probes for load balancers

GET/healthz

The process is up. Does not touch the database.

Anyone

GET/readyz

The process can reach its database and may receive traffic.

Anyone