API Reference

The Digital.ai Platform API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation.

To view a list of all endpoints with examples, see: Digital.ai Platform API Reference.

The following sections describe the API usage parameters such as Pagination, Sorting, Filtering, Bulk Operations, and Error types. These parameters are included in the request URL as query parameters.

Pagination

Pagination is necessary when you are dealing with a lot of data and endpoints. When you use a GET API request to retrieve information from a server via an API endpoint, the returned JSON file will sometimes include a large amount of data. In order to search through the database and retrieve data in smaller pieces, pagination is used, which helps in querying the database efficiently.

All endpoints that support pagination accept count and start integer query parameters. The response will include pagination meta data.

Pagination meta data:

{
    ...
    "pagination": {    
      "start": integer, # the requested start value
      "count": integer, # the requested count value
      "next_start": integer, # optional, included only if there are more records to retrieve
      "previous_start": integer, # optional
      "total_available": integer
    } 
}

Sorting

Sorting helps you to arrange data in either ascending or descending order. When you request data and want to sort the results by a condition, then you may want to use the sorting parameter to arrange the response in either ascending or descending order (sort direction).

The endpoints that support sorting accept sort query parameter. The parameter value is a comma-separated list of field names. To reverse sort direction, prefix the field name with -.

Filtering

Filtering helps you to filter out a subset of data for which the conditions applied are true.

Endpoints support multiple filter query parameters, separated by & (http url standard). For example,

...?filter="filter1"&filter="filter2. This is used to combine results of filter1 and filter2 (i.e. OR).

Each filter can contain one or more entries for "fields". For example,

...?filter="field1[operator]:value;field2[operator]:value"&filter="field1:value. In this case, the "field" entries are separated by a semicolon ;, and the result will include only the entities that satisfy all field entries (i.e. AND).

The Operators could be eq, ne, lt, le, gt, ge, in, and so on.

Bulk Operations

Using bulk operations, you can run the same operations on one or more resources within a single request.

You can use each PATCH, PUT, and DELETE endpoint to update or delete a list of entities in a single request to affect all of them. Any bulk operation must include the X-Action: bulk header.

Example:
When updating, use the PATCH or PUT route for that entity type without an ID, providing a list of objects with fields to be updated and the ID for each, rather than a single object.

The return response would include a list of updated entities, not_updated IDs, failed IDs, and errors containing the entity ID along with the error message from the server. If no entities were updated the response would be HTTP 304 Not Modified.

Error Types

All errors (4xx, 5xx) are returned in the following JSON format:

{
    "error": {
        "guid": "<uuid>",
        "code": 123,
        "message": "Message here",
        "error_details": "Optional error details"
    }
}