- REST API
- Making Requests
- Service Accounts
- Authentication
- Version
- Content Type
- Pagination
- Throttling
- Notable API Endpoints for Enterprise
- Organization Backups
- Organization Bricks
- Retrieve Deployment Engagement Reports
- Retrieve Organization Database Records
- Filtering Records
- Retrieve Archived Organization Database Records
- Data Retention Policy
- Bulk Exporting Database Records
- Creating a Database Export Job
- Retrieving a Database Export
- Merge Strategy
- Delete Organization Database Records
- Deleting a Single Record
- Clearing Records
- Update Group Membership
- Retrieve Campaign Membership
- Update Campaign Membership
REST API
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:
Click "Create Service Account" and select the Role of the account.
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 resourceGET /api/deployments/:deploymentId/reports/:reportId/
: retrieve engagement data from the report. The endpoint supports the following optional query parameters:start_date
: theYYYY-MM-DD
for data to include (inclusive)end_date
: theYYYY-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
/databases/jobs/
endpoint to create a database export jobTo 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 databasesGET /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
: theYYYY-MM-DD
for data to include (inclusive)end_date
: theYYYY-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 recordshallow
: replaces properties provided by the updatedeep
: deep merges objects in the update. For non-objects, replaces with the updatedeep_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 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/
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 organizationPUT /api/organizations/:organizationId/campaigns/:campaignId/
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"
}
}
]
}