# Data Streams REST API
Source: https://docs.chain.link/data-streams/reference/data-streams-api/interface-api

> For the complete documentation index, see [llms.txt](/llms.txt).

<DataStreams section="dsNotes" />

## Domains

| Description   | Testnet URL                                | Mainnet URL                        |
| :------------ | :----------------------------------------- | :--------------------------------- |
| REST endpoint | https\://api.testnet-dataengine.chain.link | https\://api.dataengine.chain.link |

## Authentication

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](/data-streams/reference/data-streams-api/authentication) page.

**Note**: If you're using a [Data Streams SDK](/data-streams/reference/data-streams-api/go-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. | <ul><li>`feedID`: A Data Streams stream ID.</li><li>`timestamp`: The Unix timestamp for the report.</li></ul> |

##### Sample request

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

##### Sample response

```json
{
  "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

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

##### Sample response

```json
{
  "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. | <ul><li>`feedIDs`: A comma-separated list of Data Streams stream IDs.</li><li>`timestamp`: The Unix timestamp for the reports.</li></ul> |

##### Sample request

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

##### Sample response

```json
{
  "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. | <ul><li>`feedID`: A Data Streams stream ID.</li><li>`startTimestamp`: The Unix timestamp for the first report.</li><li>`limit` (optional): The number of reports to return.</li></ul> |

##### Sample request

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

##### Sample response

```json
{
  "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: <ul><li>There is any missing/malformed query argument.</li><li>Required headers are missing or provided with incorrect values.</li></ul>                                                                                                                                                                               |
| 401 Unauthorized User                    | This error is triggered when: <ul><li>Authentication fails, typically because the HMAC signature provided by the client doesn't match the one expected by the server.</li><li>A user requests access to a stream without the appropriate permission or that does not exist.</li></ul>                                                                |
| 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. |