Data Streams REST API

Domains

Description	Testnet URL	Mainnet URL
REST endpoint to query specific reports	https://api.testnet-dataengine.chain.link	https://api.dataengine.chain.link

All requests to the Data Streams REST API require authentication. For comprehensive documentation on generating authentication headers and implementing the HMAC authentication process, please refer to the Data Streams Authentication page.

Note: If you're using a Data Streams SDK, you don't need to manually generate authentication headers.

Headers

All routes require the following three headers for user authentication:

Header	Description
`Authorization`	The user's unique identifier, provided as a UUID (Universally Unique IDentifier).
`X-Authorization-Timestamp`	The current timestamp, with precision up to milliseconds. The timestamp must closely synchronize with the server time, allowing a maximum discrepancy of 5 seconds (by default).
`X-Authorization-Signature-SHA256`	The HMAC (Hash-based Message Authentication Code) signature, generated by hashing parts of the request and its metadata using SHA-256 with a shared secret key.

API endpoints

Return a single report at a given timestamp

Endpoint

/api/v1/reports

Type	Description	Parameter(s)
HTTP GET	Returns a single report for a given timestamp.	`feedID`: A Data Streams stream ID. `timestamp`: The Unix timestamp for the report.

Sample request

GET /api/v1/reports?feedID=<feedID>&timestamp=<timestamp>

Sample response

{
  "report": {
    "feedID": "Hex encoded feedId.",
    "validFromTimestamp": "Report's earliest applicable timestamp (in seconds).",
    "observationsTimestamp": "Report's latest applicable timestamp (in seconds).",
    "fullReport": "A blob containing the report context and body. Encode the fee token into the payload before passing it to the contract for verification."
  }
}

Return a single report with the latest timestamp

Endpoint

/api/v1/reports/latest

Type	Parameter(s)
HTTP GET	`feedID`: A Data Streams stream ID.

Sample request

GET /api/v1/reports/latest?feedID=<feedID>

Sample response

{
  "report": {
    "feedID": "Hex encoded feedId.",
    "validFromTimestamp": "Report's earliest applicable timestamp (in seconds).",
    "observationsTimestamp": "Report's latest applicable timestamp (in seconds).",
    "fullReport": "A blob containing the report context and body. Encode the fee token into the payload before passing it to the contract for verification."
  }
}

Return a report for multiple FeedIDs at a given timestamp

Endpoint

/api/v1/reports/bulk

Type	Description	Parameter(s)
HTTP GET	Return a report for multiple FeedIDs at a given timestamp.	`feedIDs`: A comma-separated list of Data Streams stream IDs. `timestamp`: The Unix timestamp for the reports.

Sample request

GET /api/v1/reports/bulk?feedIDs=<FeedID1>,<FeedID2>,...&timestamp=<timestamp>

Sample response

{
  "reports": [
    {
      "feedID": "Hex encoded feedId.",
      "validFromTimestamp": "Report's earliest applicable timestamp (in seconds).",
      "observationsTimestamp": "Report's latest applicable timestamp (in seconds).",
      "fullReport": "A blob containing the report context and body. Encode the fee token into the payload before passing it to the contract for verification."
    }
    //...
  ]
}

Return multiple sequential reports for a single stream ID, starting at a given timestamp

Endpoint

/api/v1/reports/page

Type	Description	Parameter(s)
HTTP GET	Return multiple sequential reports for a single stream ID, starting at a given timestamp.	`feedID`: A Data Streams stream ID. `startTimestamp`: The Unix timestamp for the first report. `limit` (optional): The number of reports to return.

Sample request

GET /api/v1/reports/page?feedID=<FeedID>&startTimestamp=<StartTimestamp>&limit=<Limit>

Sample response

{
  "reports": [
    {
      "feedID": "Hex encoded feedId.",
      "validFromTimestamp": "Report's earliest applicable timestamp (in seconds).",
      "observationsTimestamp": "Report's latest applicable timestamp (in seconds).",
      "fullReport": "A blob containing the report context and body. Encode the fee token into the payload before passing it to the contract for verification."
    }
    //...
  ]
}

Error response codes

Status Code	Description
400 Bad Request	This error is triggered when: There is any missing/malformed query argument. Required headers are missing or provided with incorrect values.
401 Unauthorized User	This error is triggered when: Authentication fails, typically because the HMAC signature provided by the client doesn't match the one expected by the server. A user requests access to a stream without the appropriate permission or that does not exist.
500 Internal Server	Indicates an unexpected condition encountered by the server, preventing it from fulfilling the request. This error typically points to issues on the server side.
206 Missing data (`/bulk` endpoint only)	Indicates that at least one stream ID data is missing from the report. E.g., you requested a report for stream IDs `<feedID1>`, `<feedID2>`, and `<feedID3>` at a given timestamp. If data for `<feedID2>` is missing from the report (not available yet at the specified timestamp), you get `[<feedID1 data>, <feedID3 data>]` and a 206 response.

Data Streams REST API

Get the latest Chainlink content straight to your inbox.