The Divvent API
Do by API what you can do in the portal — list applications, ask for and approve changes, release, roll back and export — with a token you control.
The Divvent API lets a script or a build job do what a person can do in the portal: list your applications, ask for a change, read what the AI proposed, approve it, release a version to a test copy or to the live application, roll back, and export an application's model.
A token acts as the person who made it. It can never do more than that person's role allows today, and it can only do what its scopes allow. If an owner changes your role, every token you made changes with it on its next request. See People and roles.
Make a token
- In the portal, open Your sign-in in the header, then API tokens and webhooks.
- Under Make a token, give it a name in Its name.
- Under What it may do, tick only the scopes the job needs.
- Choose how many days until it expires: 30 unless you choose otherwise, and never more than 90.
- Press Make the token.
Making a token needs a sign-in from the last five minutes. If you are asked, sign in again and come back.
The token is shown once. Copy it straight away: Divvent keeps only a fingerprint of it. Keep it in your build system's secret store or your keychain, and give it to programs in an environment variable — never on a command line.
An editor, an admin or an owner can make tokens. A viewer or a finance approver can't. Each person can hold up to 20 live tokens. The same page lists your tokens, when each expires and when it was last used; Revoke ends one immediately. An owner sees, and can revoke, every token on the account.
You can also make a token from a terminal with the command line. See The Divvent command line.
Authenticate
Send the token as a bearer token. The API lives under the portal's address:
GET https://app.divvent.co.uk/api/v1/me
Authorization: Bearer dvt_…The API never accepts a portal sign-in cookie: only a token. A revoked or expired token is refused on its next request.
Scopes
| Scope | What it lets a token do |
|---|---|
applications:read | Read applications, changes, proposals and releases |
requests:write | Ask for changes, answer the AI, withdraw or decline a change |
changes:approve | Approve changes — a breaking or destructive one only after the person confirms in the browser |
deploys:trial | Release to test copies and roll them back, and withdraw a release nobody has started |
deploys:production | Release to the live application and roll it back, as well as test copies |
export:read | Export an application's model and its version history |
No scope reaches people, billing, connected services, domains, backups, erasure, handing an application over, the visual editors or creating an application. Those stay in the portal.
What you can do
Every path below is under /api/v1.
| Method and path | What it does |
|---|---|
GET /me | Who this token acts as, and what it may do |
POST /me/revoke | End this token now |
GET /applications | List the company's applications |
GET /applications/{applicationId} | One application, its test copies and its newest version |
GET /applications/{applicationId}/requests | Its changes, with each one's class and who may approve it |
POST /applications/{applicationId}/requests | Ask for a change, in words |
GET /applications/{applicationId}/requests/{requestId} | The conversation about a change |
POST /applications/{applicationId}/requests/{requestId}/replies | Answer the AI's question, or revise the proposal |
POST /applications/{applicationId}/requests/{requestId}/withdraw | Withdraw a change |
GET /applications/{applicationId}/requests/{requestId}/proposal | Read a proposal and its class |
POST /applications/{applicationId}/requests/{requestId}/approve | Approve it |
POST /applications/{applicationId}/requests/{requestId}/decline | Decline it, with a reason |
GET /confirmations/{confirmationId} | Whether an approval waiting on the browser has been confirmed |
GET /applications/{applicationId}/deploys | Releases and rollbacks, newest first |
GET /applications/{applicationId}/deploys/{deployRequestId} | One release's status |
POST /applications/{applicationId}/deploys | Release the newest version to a test copy, or to the live application |
POST /applications/{applicationId}/promotions | Put exactly what a test copy runs on the live application |
POST /applications/{applicationId}/rollbacks | Go back one release, and optionally put the data back too |
POST /applications/{applicationId}/deploys/{requestId}/cancel | Withdraw a release nobody has started |
GET /applications/{applicationId}/export | The application's model and its version history |
The full, machine-readable description, with every request body and answer, is at /api/v1/openapi.json on the portal.
Asking for a change spends your account's AI budget, the same as asking in the portal. See Plans and billing.
Approving a change
Read the proposal first. Its answer includes an expects value: send it back in the body when you approve. If the proposal was made again in between, the approval is refused rather than approving something you did not read.
A token can approve a change that only adds, or one that keeps everything working, if the person's role may. A breaking or destructive change always needs the person, signed in now. The API answers 202 with a confirmation link instead. The person opens it in the portal, reads the change, and presses Approve this change (or Do not approve) on a sign-in from the last five minutes. The link lasts fifteen minutes. Poll GET /confirmations/{confirmationId} to learn the outcome.
Export
The export is the application's model and its version history. Your data is not part of it: to take the data as well, use the Export page in the portal. See Export your application and your data.
Limits
- 120 requests a minute for each token, and 600 a minute for the whole company across all its tokens.
- Over a limit, the answer is
429with aRetry-Afterheader saying how many seconds to wait. - Tokens last 30 days by default and 90 at most.
Webhooks
A webhook tells an address of yours when something happens, so a job doesn't need to keep asking. Only an owner can add one, on the same API tokens and webhooks page, under Add a webhook: an HTTPS address and the events you want.
| Event | When |
|---|---|
deploy.requested | A release, promotion or rollback was asked for |
deploy.succeeded | A release finished and is live |
deploy.failed | A release failed; what was live still is, or was put back |
approval.approved | A change was approved and became a version |
approval.declined | A change was declined |
approval.confirmation_required | An approval made with a token is waiting for its person to confirm it |
Each delivery carries three headers: Divvent-Webhook-Id, Divvent-Delivery (the same across retries, so you can drop a repeat) and Divvent-Signature:
Divvent-Signature: t=<unix seconds>,kid=<key id>,ed25519=<base64url signature>The signature is Ed25519 over <t>.<Divvent-Webhook-Id>.<body>. Check it with the public key for that kid, published at /.well-known/divvent-webhook-keys on the portal. Refuse a signature more than five minutes old, and one for a webhook id that isn't yours. There is no shared secret to keep.
A delivery that fails is tried again, up to eight times over about a day and a half. The body says what happened — ids, states, a version — and never anything your application stores.
If the page says Webhooks are not switched on here yet, Divvent hasn't published its signing key on that portal, and nothing is sent.
What the API can't do yet
- Make tokens, revoke any token but itself, or add and remove webhooks. Those are in the portal only, on purpose, so a stolen token can't make another or send your events somewhere else.
- Show a webhook's delivery history, or send a test event.
- Export your data. Use the portal's Export page.