The TWAICE Ingestion API lets you send BESS operating data (voltage, current, temperature, and related sensor measurements) into the TWAICE platform for analysis.

Overview

The TWAICE Ingestion API follows REST architecture principles.
All requests must use HTTPS.
Requests and responses are JSON; set the Content-Type header to application/json on every request.

Authentication

Authentication is done via JWT Tokens. To obtain a token, use the authentication API endpoint with your email and password as credentials.
Tokens can only be obtained by registered customers with valid credentials.
- Your credentials should already have been created for you. If they haven't, contact your TWAICE representative.
The response returns an idToken. Pass it as a bearer token in the Authorization header on all subsequent requests:
```
> Authorization: Bearer JWT_TOKEN
```
The idToken is valid for 1 hour.

Request

POST /auth/authenticate

API Endpoint

Data hosted in	Endpoint
US	`https://api.us.twaice.ai/auth/authenticate`
All others	`https://api.twaice.ai/auth/authenticate`

Payload

Payload Body Schema: application/json

Field	Type
`email` (required)	string
`password` (required)	string

{
  "email": "johnDoe123@gmail.com",
  "password": "d4f089b1e7a6"
}

Responses

HTTP 201 Created: Login successful.

Response Body Schema: application/json

Field	Type
idToken	string. JWT Token used for API request authentication & authorization.

Response Sample:

{
  "idToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1ZGYy"
}

HTTP 400 Bad Request: Validation Error for the request input.

Response Body Schema: application/json

Field	Type
`status` (required)	string. Enum: `"success"`, `"error"`
`data` (required)	object
`message` (required)	string. Error message if status is `"error"`.

Response Sample:

{
  "status": "error",
  "data": { 
     "statusCode": 400, 
     "message": [ 
       "email should not be empty", 
       "Either email or username should be provided." 
      ], 
    "error": "Bad Request"
  },
  "message": "Bad Request Exception"
}

HTTP 401 Unauthorized: Invalid login credentials

Response Body Schema: application/json

Field	Type
`status` (required)	string. Enum: `"success"`, `"error"`
`data` (required)	object
`message` (required)	string. Error message if status is `"error"`.

Response Sample:

{
  "status": "error",
  "data": {
     "statusCode": 401, 
     "message": "Incorrect username or password.", 
     "error": "Unauthorized"
  },
  "message": "Incorrect username or password."
}

Ingestion

Send raw sensor measurements to the TWAICE API.

Authorization

HTTP Authorization Scheme: bearer
Bearer format: JWT Token

Authorization: Bearer <idToken>

<idToken> is the value from the authentication request (see How to Authenticate section).

Request

POST /ingestion/customers/{customer}/systems/{system}/measurements

API Endpoint

Data hosted in	Endpoint
US	`https://api.us.twaice.ai/ingestion/customers/{customer}/systems/{system}/measurements`
All others	`https://api.twaice.ai/ingestion/customers/{customer}/systems/{system}/measurements`

Path Parameters

customer and system are provided by TWAICE.

Parameter	Type
`customer` (required)	string, 1 to 32 characters, `^[a-z0-9-]*$`
`system` (required)	string, 1 to 32 characters, `^[a-z0-9-]*$`

Request Body Schema

Array ([ 1 .. 1000 ] items): Accepts up to 1000 measurement objects per request (limit can be modified in need, should be discussed with TWAICE)

Field	Type
`sensor` (required)	string, 1 to 200 characters, `^[^/]*$` Customer-provided sensor identifier, unique per system, up to 200 characters. Letters, numbers, and special characters allowed except "forward slashes (`/`).
`timestamp` (required)	number, range 946684800 to 4102444800. Unix timestamp in seconds, with optional microseconds as a fraction. Must be after 2000-01-01 00:00:00 GMT+0000 and before 2100-01-01 00:00:00 GMT+0000. Example: `1642770062.123456 == 2022-01-21T14:01:02.123456Z` (the fraction is 123.456 milliseconds, or 123456 microseconds).
`value` (required)	number. Sensor value at the given timestamp. Accepts integers or float64 (double).

Payload

[
  {
    "sensor": "Sensor XYZ",
    "timestamp": 1642770062.123456,
    "value": 12.345678
  }
]

Responses

HTTP 200: Successful Response

Response Body Schema: application/json

Field	Type
`numberOfRecordsIngested` (required)	integer, >= 0. Number of measurements ingested by this request.

Response Sample:

{
  "numberOfRecordsIngested": 1
}

HTTP 404: Not Found

Returns if there are invalid path parameters.

Response Body Schema: application/json

Field	Type
`type`	string. Default: "`about:blank`". A URI reference identifying the problem type, scoped to this API. Unlike RFC 7807, it is not required to be dereferenceable or globally unique.
`title`	string. Short summary of the problem type. Written for engineers; not localized.
`status`	integer. 100 to 599. Default 500. The HTTP status code generated by the origin server for this occurrence.
`detail`	string. Human readable explanation of this occurrence. Written for engineers; not localized.
`timestamp`	number. Range 946684800 to 4102444800. Unix timestamp in seconds with optional Microseconds as fraction. The unix timestamp is the number of seconds between a particular date and the Unix Epoch on January 1st, 1970 at UTC. Must be after 2000-01-01 00:00:00 GMT+0000 Must be before 2100-01-01 00:00:00 GMT+0000 Example: 1642770062.123456 == 2022-01-21T14:01:02.123456Z, with the fraction representing 123.456 milliseconds or 123456 microseconds respectively

Response Sample:

{
  "type": "about:blank",
  "title": "HTTPException",
  "status": 404,
  "detail": "Not Found",
  "timestamp": 1642770062.123456
}

HTTP 422: Unprocessable Entity

Returned when the request contains invalid data.

Response Body Schema: application/json

Field	Type
`type`	string. Default: "`about:blank`". A URI reference identifying the problem type, scoped to this API. Unlike RFC 7807, it is not required to be dereferenceable or globally unique.
`title`	string. Short summary of the problem type. Written for engineers; not localized.
`status`	integer. 100 to 599. Default 500. The HTTP status code generated by the origin server for this occurrence.
`detail`	string. Human readable explanation of this occurrence. Written for engineers; not localized.
`instance`	string. A URI reference identifying the specific occurrence, for example a fragment or sub-path pointing to the source of the problem.
`timestamp`	number. Range 946684800 to 4102444800. Unix timestamp in seconds with optional Microseconds as fraction. The unix timestamp is the number of seconds between a particular date and the Unix Epoch on January 1st, 1970 at UTC. Must be after 2000-01-01 00:00:00 GMT+0000 Must be before 2100-01-01 00:00:00 GMT+0000 Example: 1642770062.123456 == 2022-01-21T14:01:02.123456Z, with the fraction representing 123.456 milliseconds or 123456 microseconds respectively
`errors`	Array of objects. Detailed information about each subproblem that occurred in the request.

Response Sample:

{
  "type": "https://docs.twaice.ai/#section/422:-Unprocessable-Entity",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request contains invalid data, more information about the specific problem could be found in errors field",
  "instance": "/system/11223344/sensor/55667788",
  "timestamp": 1642770062.123456,
  "errors": [
    {
      "title": "value_error.missing",
      "detail": "field required",
      "instance": "/body/timestamp"
    }
  ]
}

HTTP 500: Internal Server Error

Returned when an error or failure occurs in the backend service.

Test Environment

TWAICE provides a sandbox environment for testing your integration without affecting live data.

Authorization: Bearer JWT_TOKEN

Path Parameters

Identical to the Path Parameters described under Ingestion. customer and system are provided by TWAICE.

Request Body Schema

Identical to the Request Body Schema described under Ingestion.

Sensor IDs must be defined in advance during system configuration. For the sandbox system, any sensor identifier can be used, since sandbox data will not be passed through the full processing pipeline.

Request Sample

[
  { 
    "sensor": "string 1.1.1-string voltage", 
    "timestamp": 1642770062.123, 
    "value": 401.2
   },
   { 
    "sensor": "string 1.1.1-string voltage", 
    "timestamp": 1642770062.123, 
    "value": 403.1
   }
]

Frequently Asked Questions

Are there any other options for submitting to the API besides a RESTful service?

No, the API currently supports only the RESTful methods described above.

At what resolution will historical data be required? Is this the same tag list for near real-time data?

The same tag list applies.
The time resolution should ideally match as well: 1 point / second if available; otherwise, 1 point / minute.

Is it possible to send large data for initial site onboarding to an S3 bucket rather than the API?

Yes, this is possible via SFTP or S3 access keys.

Can data be provided at lower time resolutions (e.g. 30 seconds)?

Resolution between 1 and 60 seconds is accepted. Lower time resolution may affect the accuracy of some KPIs.

How often should data be transmitted? As soon as it's available (near-real-time), or can it be batched? What's the impact of delayed data?

For the API, it's best to fill the 1000-record maximum batch size. Frequency and rate limits are discussed during onboarding. Delayed data transmission can lead to delayed KPI calculations, notifications, or alerting.

Must data always be delivered in chronological order?

No. Data is sorted by timestamp on ingestion.

Can we send all data in UTC?

All timestamps sent, as defined in the ingestion schema, are expected to be Unix timestamps, which are UTC-based by definition.

How would TWAICE like to be notified of failed data transmissions?

We detect gaps as "missing data". You can resend the data directly, or for longer outages, email support@twaice.com.

How should a storage system handle resending data that didn't land via the API? How often can we retry, and what's the maximum number of retries TWAICE recommends?

There is no maximum retry count from our side. If data arrives too late, we may not be able to include it in KPI calculations or alerting.

How would our system play “catch-up” if the TWAICE API becomes unavailable for some reason?

We inform the customer and fix it as soon as possible.

Does TWAICE have anomaly detection to prune poor-quality data?

We have threshold-based cleansing rules. These are configured by TWAICE for each storage, but can be tuned based on your needs.

Data Connection: Ingestion API User Guide

Overview

Authentication

Request

API Endpoint

Payload

Responses

Ingestion

Authorization

Request

API Endpoint

Path Parameters

Request Body Schema

Payload

Responses

Test Environment

Path Parameters

Request Body Schema

Frequently Asked Questions