Authentication

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

Example API request

Request

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

API_KEY is the API key that was generated in the ScalePad application.

The API key has the format c4d67eca-3b32ed26-b2412e47-2f634617-7e91a0f4-5c8d2b67-e3a19f0b-46d7c582

Creating a personal API key

User considerations

A ScalePad user must be active and have the ScalePad account Administrator permission in order to view the API tab and to use their API keys.

Please note that a user's API keys will cease to function if the user is no longer active or has the Administrator permission.

API key generation

After signing into your ScalePad account, navigate to your personal API keys

Select New API key to create a new API key for your member, and choose a name and expiration date for the API key. By default, the expiration date of your API key will be 2 years.

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

You can manage your personal API keys and delete them if you wish.

Rate limiting

The default rate limit for all ScalePad API endpoints is 50 requests per 5 seconds.

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

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

Too Many Requests

The header Retry-After indicates how long the user agent should 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.

Cursor based pagination

Request

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

Where:

• page_size refers to how many records to return in a page
• cursor refers to the pointer used to fetch a certain page of records

Response

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

Where:

• data refers to the data returned by the query, as an array
• total_count refers to the total count of all records
• next_cursor refers to the pointer used to fetch the next page of records, if more records are available

Example

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

Filtering

ScalePad API endpoints may offer filtering based on the values of fields. The fields that are filterable will be documented in the endpoint documentation.

Filter keyword filtering

Filtering is done using the filter keyword, indexed by the field name you wish to filter by. This is then followed by the filter clause, which may contain the operator(s) and value(s) you wish to filter.

Operators

These are all the operators we support. Some endpoints will only support a subset of these:

If the operator is omitted, it will be evaluated as an eq.

For example:

filter[type]=eq: WORKSTATION and filter[type]=WORKSTATION are equivalent.

Filter combinations

We support combinations of filters across all the filter parameters. These are evaluated in any order as an AND.

For example:

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

Date formats

Date fields should match the format of the field that’s 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

Please note that any strings containing special tokens should be wrapped in double quotes to ensure your query is evaluated correctly. These include:

• ,
• :
• OR
• AND

For example:

filter[name]=eq:"Space Sprockets, Inc."

Nested filters

We support filters that utilize nested properties within objects. For example, filtering by an attribute within another attribute. These are indexed using .. You may generate queries such as:

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

Sorting

ScalePad API endpoints offer sorting based on ascending or descending properties of certain fields. The fields that are sortable will be documented in the endpoint documentation.

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

Operators

These are the operators we support:

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

Combinations

Multiple fields can be sorted by delimiting the fields using a comma.

For example:

sort=num_hardware_assets,-num_contacts

Errors

ScalePad API endpoints return a standardized error structure (except 429 Too Many Requests) that adheres to the following format:

{
    "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."
        }
    ]
}

Within this structure:

• errors is an array of error objects
  • code is a string indicating what type of error it is
  • title is a short description of what the error is
  • description is a more detailed description of what the error is and possible steps to resolve it

Endpoint documentation

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