The REST API

Every path on this page sits behind the base URL below, and every request carries your key in an Authorization header. There is no other way in: no session cookie, no basic auth, no key in the query string.

curl -s https://app.provibr.com/api/v1/me \
  -H "Authorization: Bearer pvk_..."

You create a key on your own profile page, under API keys. It belongs to you and to one account: it is not shared with your colleagues, and it stops working the moment you leave that account.

• A key expires after 90 days unless you choose otherwise. You can pick a shorter term, or none at all; a key without an end date is a key you have to remember to revoke yourself.
• Rotating means creating a new key and revoking the old one, with a moment in between where both work. There is no rotation in place, because that leaves you without a working key if anything goes wrong halfway.
• You can bind a key to a list of addresses. A request from anywhere else is refused before anything is read, and that refusal tells the caller nothing about the key.
• One member holds at most 25 keys. A revoked key keeps its row, so you can still see afterwards what it was allowed to do while it lived.

A key carries scopes: read or write, per part of the panel. What it may actually do is the intersection of those scopes and the permissions of the member it belongs to.

Permissions are read live, on every request. Withdraw something from a member and every key of that member becomes narrower straight away, without anyone having to revoke anything. That is also why a key survives a role change instead of being invalidated by it.

Your infrastructure is reachable only through the agent inside your own network, and that agent connects outbound. So an endpoint that changes a machine cannot answer with the result. It answers that the order was accepted, and hands you something to follow.

1. 01You send the request and get an accepted answer, with a Location header pointing at the command that was created. That header is absolute from the host: resolve it against the origin, not against the base URL above, or you end up asking for a path that does not exist.
2. 02That same command is in the body as well, but wrapped in a command field. The read below returns it bare, without that wrapper: unwrap once and the first read is usually unnecessary.
3. 03You read the command until its status is final: done, failed, timed out or cancelled. Only pending is not final, and a status you do not recognise counts as final too, so a value added later can never leave you polling forever.
4. 04A command that failed carries the error code of the agent itself, with its arguments, the same ones the panel renders on your screen.

# 1. the order - answers 202 with a Location header
curl -s -D - -X POST https://app.provibr.com/api/v1/servers/<serverId>/actions/start \
  -H "Authorization: Bearer pvk_..."

# 2. the outcome - repeat until the status is final
curl -s https://app.provibr.com/api/v1/commands/<commandId> \
  -H "Authorization: Bearer pvk_..."

Every endpoint says what it answers with: 200 for a read, 201 for something that was created, 202 for work your agent still has to carry out. And every one of them describes the body it returns, with a name of its own per resource, so the code you generate holds one type per resource instead of one per endpoint.

Lists answer with a page and a cursor; you pass that cursor back until it comes out empty. A page holds 50 rows by default and 100 at most.

Every answer that is not a success has the same shape, whatever went wrong and wherever it went wrong.

{
  "error": {
    "code": "validation_failed",
    "message": "Name is too long (max 64).",
    "detail": "server.validation.apiKeys.nameTooLong",
    "params": { "max": 64 },
    "requestId": "3f9c1b2a-..."
  }
}

code

The word to branch on. It comes from a closed list, so a value you do not know means you are talking to a newer version than the one you built against.

message

One English sentence, for whoever reads a log. Never branch on it: the wording is free to change.

detail

A stable key, where there is one. It is the same key the panel uses for its own message, so you can put the sentence in your own language.

params

The arguments belonging to that key: a limit that was exceeded, a name that was taken, the host that refused.

requestId

The identifier of this request, also in a response header. Quote it when you ask us about something.

You may make 120 requests per minute per key, and 600 per account across all of its keys. That second limit exists so twenty keys cannot put twenty times the load on the same host.

Anything that creates something accepts a idempotency-key header of your own making. Repeat the same request with the same value and you get the first outcome back, instead of a second machine, a second key or a second command.

You may also send your own x-request-id. It comes back on the answer and appears in our logs, which is the cheapest way to lay a line from your side next to a line from ours.

There is not a single provider name in the routing of this API. Which systems you can connect, which fields their credentials take and what they are capable of is answered by the discovery endpoint, and the body you send to create an integration is built from that same register. A provider that goes live shows up in both without a single endpoint changing.

It works the other way around too. Ask something of a machine whose provider cannot do it (a console on a hosting account, a disk on a game server) and you get a refusal that names the missing capability, before anything is sent to your agent.

Grouped the way the specification groups them. Each path comes after the base URL, and next to it stands the scope the endpoint requires; where nothing stands, a valid key is enough.

The same information as an OpenAPI 3.1 document, generated from the code that serves these endpoints rather than written alongside it. Hand it to a client generator, an editor or a test suite.

curl -s https://app.provibr.com/api/v1/openapi.json

Within this version, changes are additions: new endpoints, new optional fields, new values in a list. Read fields you do not know leniently, and do not treat an error code you do not know as fatal.