Welcome to the Derapi API Reference. Here you will find details about interacting with the API and details for each endpoint.

The API is standard REST + JSON over HTTPS fully documented with OpenAPI 3.1.

We aim to comply with all major RFCs for HTTP(S) and choose the most user-friendly standard when there are competing options for our API.

SDKs

Derapi offers SDKs to more easily integrate with Derapi APIs. Our SDKs are regularly updated.

Available APIs:

Python derapi-python

If your preferred program language is not list please contact support@derapi.com.

Versioning

The Derapi API maintains versions in the format vYYYY-MM-DD. The current version is v2024-09-01. Version can be specified by setting the header api-version.

Errors

Derapi uses standard HTTP response codes to signal success or failure. In cases of failure, Derapi's response includes a description of the failure in JSON format.

When possible, programmatic details specifying your issues with your request (and any possibly remedy) will be returned.

See our errors page for details.

Pagination

List endpoints are paginated. Query string parameters pageSize and pageToken can be provided to control the pagination behavior; a property nextPageToken will be present in the response when there are more results to view. Responses may also include totalSize where available.

To get all results, in pseudocode:

results, nextPageToken = listOperation(pageSize)
while nextPageToken is not null:
    nextPage, nextPageToken = listOperation(nextPageToken)
    results += nextPage

Interval Data endpoints

Our API defines a number of interval data endpoints. These endpoints are parameterized with start, end, and summaryLevel query parameters. None of them are required, but they can all be used to construct your desired window of returned data.

Start and end are used in a standard, right-open or end-exclusive interval notation -- i.e. [start, end). The minimum value for start is the operationalSince of a site; the maximum value for end is now. Requesting data beyond operationalSince or now is a 422 error. Requesting a window size (end - start) greater than the maximum allowed for the summary level is a 422 error.

Missing Data

Within operationalSince and now, a vendor may not have data for a given interval. In such cases, our API still returns an interval with "missing": true. Our API is explicit about missing data to empower our clients and help them avoid errors in their calculations; however, if so desired, clients can pass missing=drop to omit any known missing intervals from our response. Note that, when there is missing data (particularly in the recent past), later retries may provide the data due to vendor processing latency.

Maximum window sizes

end - start has the following limits per summary level:

summary level	window size
`15mins`	49 hours (196 intervals)
`hour`	(7 * 24) + 1 hours (169 intervals)
`day`	7 * 31 days (217 intervals)
`month`	24 months (24 intervals)

Defaulting

If you don't provide any parameters, we default to the last three days of hourly data.

In most cases, summaryLevel will default to hour; if you do not specify summaryLevel but do specify both start and end, we will choose a compatible summaryLevel automatically.

If only one of start or end is provided, the other will be inferred using the following default window sizes for the provided summaryLevel.

summary level	window size
`15mins`	24 hours (96 intervals)
`hour`	3 * 24 hours (72 intervals)
`day`	3 * 31 days (93 intervals)
`month`	12 months (12 intervals)

Custom formats

Currently, Derapi extends the OpenAPI 3.1 standard with a single custom format.

date-time-tz

Where the API expects or returns date times, they are specified with the custom format date-time-tz. A date-time-tz value must specify a timezone in one of the valid ISO8601 standards.

For example:

2021-01-01T00:00:00-7:00
2021-01-01T00:00Z
2021-01-01T00:00+0:00

Example incorrect values:

2021-01-01T00:00

Tags

The Derapi API includes a tagging mechanism for objects and control events. Tags are useful for adding metadata and linking information in your application. For example, you can store your application's corresponding system ID on a Derapi Site object for easy reference.

Structure

Tags are client-defined key-value string pairs.

Any object can have up to 10 tags
Keys can have 30 URL safe characters (a-zA-Z0-9~._-)
Values can have 100 characters

Never store sensitive data, like PII or credentials, in tags.

Setting tags

For example, when creating a control event you can add a tag:

"tags": {"event-ref": "4cp-1234"}

You can also update, delete, or add tags using the PATCH request on the relevant object's /tags endpoint. To add tags simply include additional key-value pairs. To update set a new value for a particular key. Lastly, to delete set the key value to null:

{"existingKey": null}

Querying with tags

Tags will be present when requesting object details such as Control Events, Sites, Batteries, etc. For example in the Get Site details response:

{
  "id": "site-rfkzu6fkbgxzd5ib",
  ...
  "tags": {
    "environment": "production",
    "team": "alpha"
  }
}

You can also use tags to filter lists. Simply include the tag(s) in your query:

/sites?tags[team]=alpha

or

/control-events?tags[event-ref]=4cp-2345e

Or check for the presence of a particular tag:

/control-events?hasTag=event-ref

Caching and synchronization

Derapi caches inventory information about DERs from multiple vendors internally. We manage the process of synchronizing state between our system and vendor systems transparently in the background, but we also offer a way to see how up-to-date the information about a particular resource is, and to manually request synchronization if needed.

Checking cache freshness

You can see the time at which Derapi last successfully synchronized a resource with the vendor system via the lastSyncedAt property of the resource details endpoint.

For example, for a Site, you would use the Get Site details endpoint to retrieve the lastSyncedAt property:

curl \
  -H 'Authorization: apikey {api-key}' \
  https://api.derapi.com/v1/sites/{siteId}

Triggering synchronization manually

In most cases, you should rely on Derapi's automatic background synchronization process to synchronize resources with vendor systems as needed.

In rare cases, you may wish to ensure that you have the latest data for a given resource before performing a particular operation. You can trigger a manual synchronization for a specific resource using the Sync resource endpoint for each resource type:

curl \
  -X POST \
  -H 'Authorization: apikey {api-key}' \
  https://api.derapi.com/{resourceType}/{resourceID}/sync

Note that manual synchronization triggered in this way is asynchronous and best-effort. If the target resource has already recently been synchronized with the vendor system, Derapi may choose to ignore a synchronization request.

If you want to be able to determine when a manual refresh has happened, you can poll the lastSyncedAt property of the resource details page until it changes:

If you choose to implement polling like this, you should ensure that you place a hard limit on the maximum wait time, since your synchronization request may be skipped.