> For the complete documentation index, see [llms.txt](https://docs.allscale.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allscale.io/allscale-checkout/api-reference/api-doc-test-route.md).

# API Doc - Test Route

**AllScale Open API**\ **Version:** v1\
**Last updated:** 2026-01-23\
**Base Path:** `/v1/test`

***

### Overview

The Test API provides endpoints used to verify:

* API authentication
* Request signing
* Replay protection
* Error handling behavior
* JSON body hashing and parsing

All endpoints require valid authentication using the HMAC-based signing mechanism.

***

### Authentication

All requests must include the following headers:

| Header      | Description               |
| ----------- | ------------------------- |
| X-API-Key   | API key                   |
| X-Timestamp | Unix timestamp (seconds)  |
| X-Nonce     | Unique request identifier |
| X-Signature | HMAC signature            |

Requests missing any of these headers will be rejected.

***

### GET /v1/test/ping

#### Description

Health-check endpoint used to verify:

* API connectivity
* Signature correctness
* Authentication configuration

#### Request

```
GET /v1/test/ping
```

Headers:

```
X-API-Key: <your_api_key>
X-Timestamp: <unix_timestamp>
X-Nonce: <uuid>
X-Signature: v1=<signature>
```

#### Successful Response

```json
{
  "code": 0,
  "payload": {
    "pong": "ok"
  },
  "error": null,
  "request_id": "req_xxxxx"
}
```

#### Response Fields

| Field        | Description               |
| ------------ | ------------------------- |
| code         | 0 indicates success       |
| payload.pong | Always returns "ok"       |
| error        | Always null               |
| request\_id  | Unique request identifier |

#### Possible Errors

| Code  | Meaning                        |
| ----- | ------------------------------ |
| 20001 | Missing authentication headers |
| 20002 | Invalid signature              |
| 30001 | Forbidden (IP not allowed)     |
| 40001 | Rate limit exceeded            |

***

### GET /v1/test/fail

#### Description

This endpoint always returns a validation error.\
It is used to test client-side error handling and error parsing.

#### Request

```
GET /v1/test/fail
```

Headers:

```
X-API-Key: <your_api_key>
X-Timestamp: <unix_timestamp>
X-Nonce: <uuid>
X-Signature: v1=<signature>
```

#### Error Response

```json
{
  "code": 10001,
  "payload": null,
  "error": {
    "message": "Validation error",
    "details": {}
  },
  "request_id": "req_xxxxx"
}
```

#### Error Code

| Code  | Meaning          |
| ----- | ---------------- |
| 10001 | Validation error |

***

### POST /v1/test/post

#### Description

Echo test endpoint. Used to verify:

* Request signing
* Body hashing
* JSON parsing
* Response format

#### Request

```
POST /v1/test/post
```

Headers:

```
X-API-Key: <your_api_key>
X-Timestamp: <unix_timestamp>
X-Nonce: <uuid>
X-Signature: v1=<signature>
Content-Type: application/json
```

Body (example):

```json
{
  "everything": "is_fine"
}
```

#### Successful Response

```json
{
  "code": 0,
  "payload": {
    "your_request_body": {
      "everything": "is_fine"
    }
  },
  "error": null,
  "request_id": "req_xxxxx"
}
```

#### Notes

* The request body may include any valid JSON object.
* The response returns the request body under `payload.your_request_body`.

#### Possible Errors

| Code  | Meaning                              |
| ----- | ------------------------------------ |
| 20001 | Missing authentication headers       |
| 20002 | Invalid signature                    |
| 30001 | Forbidden (IP not allowed)           |
| 40001 | Rate limit exceeded                  |
| 10001 | Validation error (invalid JSON body) |

***

### Usage Recommendations

* Use `/v1/test/ping` to verify authentication setup
* Use `/v1/test/post` to verify body signing (hashing) and JSON parsing
* Use `/v1/test/fail` to test error parsing
* Always log `request_id` for debugging
* Ensure timestamps are in UTC
* Never reuse nonces

***

### Notes

* All test endpoints require valid authentication
* Requests are subject to replay protection
* Responses follow the standard API response format

***

End of document.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.allscale.io/allscale-checkout/api-reference/api-doc-test-route.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.