Authentication

Authenticate ScalePad API calls using the x-api-key header.

Example request

GET https://api.scalepad.com/core/v1/clients HTTP/1.1
accept: application/json
x-api-key: <API_KEY>

Replace API_KEY with the API key generated in the ScalePad application. API keys follow this format:

c4d67eca-3b32ed26-b2412e47-2f634617-7e91a0f4-5c8d2b67-e3a19f0b-46d7c582

Creating a personal API key

User requirements

A ScalePad user must be active and have the Administrator permission to view the API tab and use API keys. If a user is deactivated or loses the Administrator permission, their API keys will stop working.

Generating a key

1Navigate to your API keys

Sign in to your ScalePad account and go to your personal API keys page.

2Create a new API key

Select New API key, then choose a name and expiration date. By default, API keys expire after 2 years.

3Copy your secret key

After selecting Generate, copy your secret API key. This is the key you will use in API calls to ScalePad.

4Manage your keys

You can manage and delete your API keys at any time from the same page.

Rate limiting

If you exceed the rate limit, the API will return a 429 response:

HTTP/1.1 429 Too Many Requests
Retry-After: 23

Too Many Requests

The Retry-After header indicates how long to wait (in seconds) before making a follow-up request.

HTTP response codes

ScalePad API uses standard HTTP response codes.

Pagination

ScalePad API endpoints use cursor-based pagination.

Due to the nature of cursor-based pagination, results are not guaranteed to be atomic across pages. Records created or updated during pagination may be skipped, and in rare cases the same record may appear on more than one page. These behaviours are expected and should be anticipated by API consumers.

Example request

{
  "page_size": 100,
  "cursor": "WyI1Y2IyNGI2ZS0wNz"
}

Example response

{
  "data": [],
  "total_count": 1,
  "next_cursor": "kLTRkMDItODI0NC01ZDI4"
}

Example URL

GET https://api.scalepad.com/core/v1/clients?page_size=200&cursor=WyIwMDVlNTg0OTk

Filtering

ScalePad API endpoints may offer filtering based on field values. Filterable fields are documented on each endpoint.

Filtering uses the filter keyword, indexed by the field name, followed by an operator and value.

Operators

If the operator is omitted, it defaults to eq. For example, filter[type]=eq:WORKSTATION and filter[type]=WORKSTATION are equivalent.

Combining filters

Multiple filters are evaluated as an AND condition.

filter[type]=eq:WORKSTATION&filter[client_id]=eq:2220324

Date formats

Date fields should match the format of the field being filtered. Date-time fields can often be filtered as a date as well.

filter[record_updated_at]=lte:"2020-03-04T00:00:00.000"
filter[record_updated_at]=gt:"2022-05-07"

Special tokens

Strings containing any of the following tokens must be wrapped in double quotes:

Nested filters

Filters support nested properties using . notation.

filter[configuration.ram_bytes]=lte:8000000000
filter[software.antivirus_info.status]=eq:RUNNING

Sorting

ScalePad API endpoints offer sorting by ascending or descending order on supported fields. Sortable fields are documented on each endpoint.

The sort parameter is sort or sort_by depending on the endpoint.

Operators

If no operator is specified, ascending order is used by default.

Combining sorts

Multiple sort fields can be specified using a comma delimiter.

sort=num_hardware_assets,-num_contacts

Rich text fields

Some ScalePad API fields accept rich text content in ProseMirror JSON format.

Example document

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "Heading" }]
    },
    {
      "type": "paragraph",
      "attrs": { "textAlign": "left" },
      "content": [
        { "type": "text", "text": "Normal " },
        { "type": "text", "marks": [{ "type": "bold" }], "text": "Bold" },
        { "type": "text", "text": " " },
        { "type": "text", "marks": [{ "type": "italic" }], "text": "Italic" },
        { "type": "text", "text": " " },
        {
          "type": "text",
          "marks": [{ "type": "link", "attrs": { "href": "https://example.com" } }],
          "text": "Link"
        }
      ]
    },
    {
      "type": "bulletList",
      "content": [
        {
          "type": "listItem",
          "content": [
            { "type": "paragraph", "content": [{ "type": "text", "text": "Bullet item" }] }
          ]
        }
      ]
    }
  ]
}

Errors

ScalePad API endpoints return a standardized error structure (except 429 Too Many Requests):

{
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "title": "No API credentials",
      "detail": "No API credentials were provided. Please check your API credentials are sent in the header 'x-api-key' or review the API documentation."
    }
  ]
}

Endpoint documentation

You can find the full documentation for all available ScalePad API endpoints under the API Reference tab.