Request & Response Conventions

ChainIT APIs are designed around a consistent set of request and response conventions that apply uniformly across all endpoints. This predictability significantly reduces integration complexity, since the same parsing logic, error handling patterns, and pagination approach work identically regardless of which API resource you are working with.

Data Format

All ChainIT API endpoints accept and return data in JSON format (application/json). Request bodies must be encoded as valid JSON and sent with the Content-Type: application/json header. All response bodies from the API are JSON, even for error responses.

String values use UTF-8 encoding. Dates and timestamps are represented in ISO 8601 format (e.g., 2025-06-15T10:30:00Z) and are always expressed in UTC unless otherwise specified.

Required Request Headers

Header	Description
Content-Type: application/json	Required for all GET, POST, PUT, PATCH and DELETE requests with a body.
Authorization: Bearer {token}	Required for all authenticated requests. See Authentication Overview.
Accept: application/json	Recommended to indicate the expected response format.
X-Request-ID	Optional. A client-supplied unique identifier for the request, returned in the response for tracing.

---

Standard Response Envelope

All API responses are wrapped in a consistent envelope structure. This ensures that client applications can process any response — success or error — using a single, shared parsing pattern.

Successful responses follow this structure:

{
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-06-15T10:30:00Z"
  }
}

List responses include a pagination object within the meta field:

{
  "data": [ ... ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-06-15T10:30:00Z",
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "totalPages": 8,
      "totalItems": 200
    }
  }
}