REST API

Everything you do in the Plexivo console goes through the same REST API, so you can automate it. Requests and responses are JSON over HTTPS.

Base URL#

https://api.plexivo.io/api/v1

In paths, an organisation is a tenant: /tenants/{tenant_id}/…. GET /tenants lists your organisations, with their ids.

Authentication#

Send an API key as a bearer token on every request:

curl https://api.plexivo.io/api/v1/tenants \
  -H "Authorization: Bearer $PLEXIVO_TOKEN"

A key works only for the organisation it was made in, and only within its permissions. A missing, wrong or expired key is answered with 401; a key without the needed permission, or used for another organisation, with 403.

Managing people and access, such as members, invitations, roles, policies and API keys, needs a person signed in to the console. API keys are refused there by design.

Requests and responses#

• Send JSON bodies with Content-Type: application/json. Responses are JSON.
• Times are ISO 8601 in UTC. Money is in US cents, in fields that end in _cents.
• Every response carries an x-trace-id header. Quote it when you contact support.

Long-running changes#

Creating, resizing or deleting a resource takes time. The response returns at once with the resource and an operation. Follow the operation with GET /operations/{id} until its state is final. A create answers 201 when the resource is being built, or 202 when it is waiting for capacity; it is not charged while it waits.

Prices before you create#

Ask for a price first with POST /tenants/{tenant_id}/deployments/estimate. The answer has the estimate, anything that would stop the create in blockers, and a quote_token valid for 5 minutes. Send the quote_token with the same body to POST /tenants/{tenant_id}/deployments, and Plexivo creates the resource only at that price: if anything changed, the create is refused with quote_changed or quote_expired.

GET /tenants/{tenant_id}/create-capabilities lists what each product can be created with, and GET /reference lists regions, sizes and other options.

Idempotency#

Network calls fail. To retry a POST, PUT, PATCH or DELETE safely, send an Idempotency-Key header with a unique value of up to 256 bytes, such as a UUID:

curl -X POST https://api.plexivo.io/api/v1/tenants/$TENANT/deployments \
  -H "Authorization: Bearer $PLEXIVO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b0e2f4c-…" \
  -d @create.json

• A retry with the same key and body gets the first response again, with the header Idempotency-Replayed: true. Nothing is done twice.
• The same key with a different body is refused with 409 idempotency_key_reused.
• While the first request is still running, a retry gets 409 idempotency_in_flight. Wait and retry with the same key.
• A request that failed does not use up its key: fix the problem and retry with the same key.
• Keys are remembered for 48 hours.
• A response that contained a one-time secret, such as a new password, is never replayed. The retry gets 409 with response_not_replayable; check the resource before you try again.

Pagination#

Long lists come a page at a time, newest first. Pass limit for the page size; when there is more, the response carries a cursor that you send back for the next page. When the cursor is null, you have everything.

Errors#

An error answers with an HTTP status and a body you can act on:

{
  "error": {
    "code": "quota_exceeded",
    "message": "…",
    "details": { … }
  }
}

Use code in your program; message is for people and may change. Idempotency errors use the application/problem+json format, with code, detail and a fix. Every code is in Error codes.

Rate limits#

Plexivo limits how fast requests arrive, so one busy script cannot slow down everyone else. Each layer answers 429 when you go over, with a Retry-After header in seconds for the per-minute limits:

When you get a 429, wait for Retry-After seconds (or a few seconds when there is none) and retry with the same Idempotency-Key.

Main endpoints#

Paths are relative to the base URL. {tenant_id} is your organisation’s id.

Organisations and projects#

Apps, databases and caches#

Plexivo App Runner#

Databases#

Plexivo Kubernetes and Plexivo Secrets#

Observability#

Billing#

For an API key, reading the wallet and any change that moves money need the billing permission.

Paying, buying a plan and making a commitment are best done in the console, where you see and confirm the price.

Next steps#