📖
PixieBrix Documentation
📡

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, where “YOURTOKEN” is the token from the above step:

Authorization: Token YOURTOKEN

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:

You can request a specific page using the page query param. For example:

/api/database/:databaseId/records?page=2

You can control the page size (maximum 1,000) using the page_size query parameter. For example: 

/api/database/:databaseId/records?page_size=150

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

Organization Bricks

Use the GET /api/organizations/:organizationId/bricks/ endpoint to get all bricks tied to your organization.

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

💽
You can retrieve up to 10,000 records per request via the records endpoint. To bulk export records across one or more databases use the /databases/jobs/ endpoint to create a database export job

To retrieve 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)

Filtering Records

The endpoint supports the following optional query parameters to filter by record creation date:

  • start_date: the YYYY-MM-DD for data to include (inclusive)
  • end_date: the YYYY-MM-DD for data to include (inclusive)

Both _date query parameters are optional. For example, to get all records since a date, use the start_date query parameter by itself:

  • /api/databases/:databaseId/records/?start_date=2022-05-19

The endpoint also supports filtering by a string data value by using a data__ param:

  • data__field_name=value

To filter for null vs. non-null, use the __isnull suffix:

  • data__field_name__isnull=true

For example:

  • data__first_name=david
  • Field names are case-sensitive and values should be URL encoded. For example, to filter by “user email”: data__user%20email%3Ddavid%40pixiebrix.com

Retrieve Archived Organization Database Records

To retrieve organization database records that have been archived to S3, use GET /api/organizations/:organizationId/databases/:databaseId/record-archives/. Note, only version 2.0 of this endpoint is supported (see Content Type section) which returns paginated results.

The response is a list objects. Each object includes a file which consists of all records that were updated on that particular date in JSONL format:

[
  {"file": "2023-01-04.jsonl", ...},
  {"file": "2023-01-02.jsonl", ...},
  {"file": "2023-01-01.jsonl", ...},
]

The list is ordered by date is descending order by default. You can list by date in ascending order using the ordering=date query param:

# GET /api/organizations/:organizationId/databases/:databaseId/record-archives/?ordering=date
[
  {"file": "2023-01-01.jsonl", ...},
  {"file": "2023-01-02.jsonl", ...},
  {"file": "2023-01-04.jsonl", ...},
]

If a date is missing, like “2023-01-03” is in the example above, then there are no records for that date.

Every file is accessible for download for 1 hour. After time expires, you will have to hit the endpoint again to get a fresh S3 link to download it.

Note, the archive does NOT reflect all changes to a Record. The archive file for a given date is generated after the date has ended. Therefore, if a Record is written to 100 times on a given date, then the archive will only display the last update to that Record.

Data Retention Policy

Every database has a limit of 500,000 records. Once that limit is exceeded, a nightly cron job will archive all records from the oldest date(s) to S3 until the database’s record count falls back under the limit. Archived records are only accessible through the Database Record Archive API. They will not be returned by the general Database Record API, which includes filtering capabilities.

Bulk Exporting Database Records

To bulk export export records from one or more databases, submit an export request

  • POST /api/databases/jobs/
  • GET /api/databases/jobs/:pk/

Creating a Database Export Job

To create a database export job, submit a POST /api/databases/jobs/ request:

{
  "name": "Custom Filename Prefix",
  "databases": ["6b69640e-d20e-45ef-a222-2cbb76bd6de8"],
  "media_type": "application/xlsx",
  "filters": {
    "start_date": "2022-05-19"
  }
}

  • Name: a custom name for the export file. The filename of the export will be this name combined with a timestamp
  • Databases: one or more database ids to retrieve records from
  • Media Type: the format for the export. One of:
    • JSON: application/json
    • Excel: application/xlsx
    • CSV: application/csv
  • Filters: filters to apply to the export. The same filters as the /api/databases/:databaseId/records/ are available. However, the filters are passed in the JSON payload of the request, not the query parameters of the request

Retrieving a Database Export

To retrieve the status and result of a database export job, call the GET /api/databases/jobs/:pk/ endpoint with the id that was returned from the job creation request

If the job was successful, the data property in the response be a URL to download the exported data file.

Add/Update Organization Database Records

To update organization database records, use the records endpoint:

  • PUT /api/databases/:databaseId/records/

The payload is the unique record id and data:

{
  "id": "todd@pixiebrix.com",
  "data": {
    "isCool": true,
    "heightInMeters": 1.93
  }
}

Merge Strategy

  • replace (default): replaces the entire record
  • shallow: replaces properties provided by the update
  • deep: deep merges objects in the update. For non-objects, replaces with the update
  • deep_append: like deep, but lists are appended instead of merged

Example: replace

Before

{
   "foo": 42
}

Update

{
   "id": "2f05955d-8652-4d92-9c4b-f2d16a1345b0",
   "data": {
      "bar": "hello"
   }
}

After

{
   "bar": "hello"
}

Example: shallow merge

Before

{
   "foo": 42
}

Update

{
   "id": "2f05955d-8652-4d92-9c4b-f2d16a1345b0",
   "mergeStrategy": "shallow",
   "data": {
      "bar": "hello"
   }
}

After

{
   "foo": 42,
   "bar": "hello"
}

Example: deep merge

Before

{
   "person": {
     "firstName": "David",
     "lastName": "Lovering"
   }
}

Update

{
   "id": "2f05955d-8652-4d92-9c4b-f2d16a1345b0",
   "mergeStrategy": "deep",
   "data": {
       "person": {
         "lastName": "Byrne"
       }
   }
}

After

{
   "person": {
     "firstName": "David",
     "lastName": "Bryne"
   }
}

Delete Organization Database Records

🛡️
Deleting records requires an Admin role

Deleting a Single Record

To delete a record in a database, use the delete record endpoint:

  • DELETE /api/databases/:databaseId/records/:key/

If your key contains spaces or special characters, you must URL encode the key in order for the URL to be a valid URL

Clearing Records

To delete multiple records in a database, use the delete records endpoint:

  • DELETE /api/databases/:databaseId/records/

The delete/clear endpoint supports the same filters as the list endpoint. See Section Retrieve Organization Database Records.

Update Group Membership

To update the members of a Group, use the memberships endpoint:

  • PUT /api/groups/:groupId/memberships/

⚠️
The members list you provide will replace the current membership list. Existing members that are not in the payload will be removed from the group

To include an email, the user must be either: 1) already a member of your organization, or 2) have an email domain that has been verified for your organization. To verify an email domain for your organization, contact support@pixiebrix.com

Example payload: 

[
  {"email": "david@pixies.com"}, 
  {"email": "paz@pixies.com"} 
]

Retrieve Campaign Membership

To retrieve membership information for a given campaign, use the following endpoint:

  • GET /api/organizations/:organizationId/campaigns/:campaignId/members/

Update Campaign Membership

To update the name or members of a Campaign, use the campaign resource endpoint:

  • GET /api/organizations/:organizationId/campaigns/: list campaigns in your organization
  • PUT /api/organizations/:organizationId/campaigns/:campaignId/

⚠️
The members list you provide will replace the current membership list. Existing members that are not in the payload will be removed from the campaign

To include an email, the user must be either: 1) already a member of your organization, or 2) have an email domain that’s been verified for your organization. To verify an email domain for your organization, contact support@pixiebrix.com

The users list supports a data property where you can provide custom master data about the users for reporting, e.g., Location, Organization Unit, etc.

Example payload:

{
  "name": "Campaign Name",
  "users": [
    {
      "email": "paz@pixies.com",
      "data": {
         "Location": "New York, NY"
      }
    }
  ]
}

Twitter