Guides

Getting Started

Suggest Edits

Follow these steps to get started building your application using Derapi’s API. Use our SDKs for even faster integration.

Get credentials

If you don’t have your Derapi client_id and client_secret please visit https://derapi.com/get-started/ to sign up for a Derapi account.

Credential Types - The Derapi API can be used in two modes, Virtual and Production. Virtual mode credentials can be created using the link above and allow getting started using our API with Virtual Devices. To control real DERs please contact us ([email protected]) to request Production credentials.

Authenticate to Derapi

Derapi uses OAuth2 client_id and client_secret for authentication. Our authentication endpoint is https://auth.derapi.com/oauth2/token. Derapi access tokens expire after 1 hour. If your access token expires you should repeat the same process to obtain a new access token.

To acquire a bearer token:

$ curl -u client_id:client_secret \
       -d "grant_type=client_credentials" \
       -X POST https://auth.derapi.com/oauth2/token

The endpoint will respond with JSON similar to the following:

{
  "access_token": "eyJraWQiOiJTd2d0NEFiUCsxNnVTaFJDdnR5aVdGUnpHRlNVd3dcL2xLbUU5",
  "expires_in": 3600,
  "token_type": "Bearer",
  "expires_at": 1723843415.017463
}

Derapi IDs URLs and IDs

The Derapi API structure access to DERs via URLs that reference the specific resource. Objects such as sites, inverters, and batteries each have a unique URL associated with that resource's unique identifier.

  • The URL structure is generally: Derapi Base URL + ID
  • The resource ID also indicates resource type: site, batt, solr
  • For example: https://api.derapi.com/batteries/batt-3e754i27ugnhqbfv

Test with Virtual Devices

Derapi provides endpoints to provision virtual devices to enable and configure various testing scenarios. These endpoints are accessible via the API URL (api.derapi.com) and require Virtual Mode credentials. These credentials are distinct from Production credentials which allow access to real devices. Virtual Devices are identified via the virtual vendor string. Virtual device-specific endpoints are detailed in our API Reference.

To get started use the https://api.derapi.com/virtual/sites endpoint to create a virtual site. This will return a Site ID you can use in subsequent requests to site-related endpoints. Specific devices such as https://api.derapi.com/virtual/batteries and https://api.derapi.com/virtual/solar-inverters can be created and associated with virtual sites you create. Up to 100 of each virtual resource type can be created. Interval data requests to virtual sites and devices return the appropriately-shaped test data. Lastly, each virtual resource can be deleted. Delete supports the common use case to programmatically create and adjust sets of devices for different testing scenarios.

An example request for creating a Virtual Solar Inverter (note that since a Site ID is not specified, one will be created implicitly):

$ curl -H "Authorization: Bearer <token>" \
        -H 'Content-Type: application/json' \
        --data '{}' \
        -X POST https://api.derapi.com/virtual/solar-inverters

The response will look similar to:

{
  "report-date-utc": "2023-01-01T23:59:00+00:00",
  "model": "Derapi Virtual Inverter",
  "serial-number": "9900010",
  "name": "My Derapi Inverter",
  "recent-production": {
    "kwh": 11.8,
    "start-date-utc": "2023-01-01T00:00:00+00:00"
  },
  "lifetime-production": {
    "kwh": 999.8877,
    "start-date-utc": "2022-01-01T00:00:00+00:00"
  },
  "recent-errors": [
  ],
  "site-id": "https://api.derapi.com/sites/site-3f754g87ugnh3bre",
  "id": "https://api.derapi.com/solar-inverters/solr-4e754i27ug1cb99v"
}

Please keep in mind that virtual devices cannot be accessed via Production mode credentials, the devices and /virtual/ endpoints are only accessible via your Virtual mode credentials.

Updated 13 days ago