📡

Developer API

REST API

📖

PixieBrix's OpenAPI Specification is available at https://app.pixiebrix.com/api/docs/

PixieBrix supports a REST API for controlling your organization, including groups, permissions, deployments, and more.

Making Requests

Service Accounts

Service Accounts are API-only users that are permissioned as human organization members, but do not count toward your Organization's subscription utilization.

To create a service, account Click "Service Accounts" on the My Teams page:

image

Click "Create Service Account" and select the Role of the account.

ℹī¸

You cannot change the Role for the account after you create it

image

When you create the account, PixieBrix will display a "Service Account Created" modal with the token for the service account. (See the Authentication section below)

Authentication

To authenticate with the REST API, provide an Authorization header with the token for the user:

Authorization: Token abc123

Version

The PixieBrix API is versioned using the Accept header. We follow Semver and will increment the major version on any backward incompatible changes.

The latest version of the API is version=2.0:

Accept: "application/json; version=2.0"

Content Type

The PixieBrix API accepts and responds with JSON. However, certain endpoints can also return other formats (notably, CSV). Refer to the OpenAPI specification for which content types a given endpoint supports

To control the response format, vary the mime type in the Accept header:

Accept: "application/json; version=2.0"
Accept: "text/csv; version=2.0"

Pagination

Pagination information is included in responses via the Link header. See https://datatracker.ietf.org/doc/html/rfc8288 for more detailed information.

Most languages have library support for working with Link headers:

Throttling

The API endpoints are throttled on a per-token basis to prevent abuse. If you make too many requests within a given minute, the server will respond with 429 Too many requests

Notable API Endpoints for Enterprise

This section describes notable API endpoints for use in the enterprise

Organization Backups

To export your organization's information as a single JSON object (e.g., for compliance), use the GET /api/organizations/:organizationId/backup/ endpoint

The backup includes all information managed by your organization except for sensitive information (e.g., shared credentials, user authentication tokens, etc.)

Retrieve Deployment Engagement Reports

To get member engagement metrics for a deployment (e.g., for use with a Business Intelligence tool such as Tableau or PowerBI), use the reports endpoint:

  • GET /api/deployments/:deploymentId/reports/: list reports for a deployment. Will always return a list containing a single resource
  • GET /api/deployments/:deploymentId/reports/:reportId/: retrieve engagement data from the report. The endpoint supports the following optional query parameters:
    • start_date: the YYYY-MM-DD for data to include (inclusive)
    • end_date: the YYYY-MM-DD for data to include (inclusive)

The report endpoint also supports the text/csv content type (see Content Type documentation above)

Retrieve Organization Database Records

To get organization database records (e.g., for use with a Business Intelligence tool such as Tableau or PowerBI), use the databases and records endpoints:

  • GET /api/organizations/:organizationId/databases/: list the Organization's databases
  • GET /api/databases/:databaseId/records/: lists the contents of a database

The records endpoint also supports the test/csv content type (see Content Type documentation above)