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.jsonAuthentication
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