Skip to content

Overview

Access to the Parallax API is available exclusively to Parallax API customers. To learn more about becoming a Parallax API customer, please reach out to your Customer Success Manager.

All Parallax API calls are made under https://api.getparallax.com and all responses return standard JSON. The following HTTP methods are supported:

  • GET
  • POST
  • PATCH
  • DELETE

Authentication

The API can be accessed by creating a Personal Access Token in the Parallax application.

Personal Access Tokens, once generated, will need to be copied and saved somewhere safe. You will not be able to see the Personal Access Token again after generating. In the event you forget to copy/lose the token, you'll need to create a new one.

Once generated, Personal Access Tokens can be sent in the X-API-KEY header. Each request will require the Personal Access Token to access the API.

We had formerly documented Authorization: Bearer here, but we will reserve that for future use with OAuth/JWTs. Please use the X-API-KEY header for Personal Access Tokens.

Authentication Example

curl -H "X-API-KEY: $ACCESS_TOKEN" \
     https://api.getparallax.com/v1/projects

Rate Limiting

Parallax enforces rate limits to ensure reliability and fair usage. We maintain the flexibility to adjust the limitations as needed, ensuring they are always set high enough to support the proper functioning of a well-behaved interactive program.

Parallax API uses a Fixed Window strategy, allowing a limited number of requests within a defined time window per user. If this limit is exceeded, the API will return a 429 Too Many Requests response, along with a Retry-After header indicating when it’s safe to retry.

  • Rate Limit set to 100 requests within a 60 second window

We recommend clients respect the Retry-After header and implement exponential backoff or retry logic accordingly.

Pagination

To standardize and simplify data retrieval across listing endpoints, we implement a consistent pagination strategy that includes request parameters, response structure, and default behavior.

Request Parameters

All list endpoints accept the following query parameters:

ParameterTypeRequiredDescriptionConstraints
pageIntegerYesThe page number to retrieveMust be ≥ 1
pageSizeIntegerYesNumber of items per pageMust be ≥ 1 and ≤ 500

Default values:

  • page: 1
  • pageSize: 500

Example:

GET /v1/clients?page=2&pageSize=10

Response Structure

Responses from paginated endpoints include a paging object with metadata, and a results array with the items for the current page.

Example JSON Response

{
  "count": 1,
  "total": 151,
  "page": 16,
  "total_pages": 16,
  "page_size": 10,
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "is_archived": true,
      "created_date": "2019-08-24T14:15:22Z",
      "modified_date": "2019-08-24T14:15:22Z"
    }
  ]
}

Response Properties

PropertyTypeDescription
countIntegerNumber of elements returned on the current page
totalIntegerTotal number of elements across all pages
pageIntegerCurrent page number
page_sizeIntegerNumber of elements per page
total_pagesIntegerTotal number of pages available based on pageSize
resultsArray<T>List of paged results of type T

Error Codes

Unless otherwise specified, endpoints follow these standard error responses:

Status CodeDescription
400Bad Request (validation errors)
401Unauthorized
403Forbidden
404Not Found
409Conflict (business rule failed)
422Unprocessable Entity (process validation)
429Too Many Requests
500Internal Server Error

Error Response Examples

400 Bad Request — validation failure

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errors": {
     "Name": [
        "The 'name' field is required.",
     ] 
  },
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400
}

409 Conflict — business rule violation

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "type": "https://url-to-error/type/description",
  "title": "Conflict",
  "status": 409,
  "detail": "something exists with this name"
}

422 Unprocessable Entity — business process failure

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "type": "https://url-to-error/type/description",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Unable to assign a user to a role that does not exist for this organization."
}

429 Too Many Requests — rate limit error

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "Rate limit exceeded. Please try again in 60 seconds."
}

500 Internal Server Error — unexpected crash

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again later."
}
 
Next page