> ## Documentation Index
> Fetch the complete documentation index at: https://utilsio.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# General

> Complete documentation for the utilsio REST API with detailed specifications and examples.

<Note>
  It is recommended to use one of our [official SDKs](/sdks) for the best support and ease of integration.
</Note>

## Overview

* **Base URL:** `https://utilsio.dev/api/v1`
* **Authentication:** HMAC-SHA256 signatures
* **Content Type:** `application/json`

## Authentication

All requests must be cryptographically signed using your App Secret. This signature-based authentication ensures that:

* Requests originate from your application (not a third party)
* Request data has not been tampered with
* Requests are recent

### Signing Requirements

Every request requires two headers:

| Header                | Description                                              |
| :-------------------- | :------------------------------------------------------- |
| `X-utilsio-Timestamp` | Unix timestamp in seconds when the signature was created |
| `X-utilsio-Signature` | HMAC-SHA256 signature over the message                   |

### Signing Logic

The signature is computed over a message in this format:

```
${deviceId}-${appId}-${timestamp}${additionalData ? `-${additionalData}` : ""}
```

Where:

* `deviceId` - The device ID associated with the request
* `appId` - Your Application ID (from query parameter)
* `timestamp` - Unix timestamp in seconds (must be within a small allowable skew)
* `additionalData` - Optional additional data (used for DELETE subscription requests)

### Timestamp Requirements

* Must be the current Unix timestamp in seconds (not milliseconds).
* Requests with expired or future timestamps are rejected with **401 Unauthorized**.

## CORS Headers

The API supports CORS with the following headers:

```
Access-Control-Allow-Origin: <request-origin>
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-utilsio-Signature, X-utilsio-Timestamp
Access-Control-Allow-Credentials: true
```

Preflight requests (OPTIONS) are automatically handled.

## Caching

Some endpoints return cache headers:

| Header          | Value                 | Meaning                   |
| :-------------- | :-------------------- | :------------------------ |
| `Cache-Control` | `public, max-age=300` | Cache for 5 minutes       |
| `ETag`          | Version identifier    | Used for cache validation |

## Error Handling

All error responses include a `success: false` flag and an `error` string:

```json theme={null}
{
  "success": false,
  "error": "Error message"
}
```

**Common Errors:**

| Error                                                              | Cause                                  |
| :----------------------------------------------------------------- | :------------------------------------- |
| `X-utilsio-Signature and X-utilsio-Timestamp headers are required` | Missing signature or timestamp header  |
| `appId is required`                                                | Missing appId query parameter          |
| `Invalid or expired timestamp`                                     | Timestamp outside of accepted window   |
| `Invalid signature`                                                | Signature doesn't match computed value |