Request & Response Conventions

Request Headers

Header
Description

Content-Type

Must be application/json for POST/PUT/PATCH requests

x-thegrid-signature

Base64-encoded Ed25519 signature

x-thegrid-timestamp

Unix timestamp in seconds

x-thegrid-fingerprint

SHA256 hash of your public key (Base64-encoded)

Example Request Headers:

Content-Type: application/json
x-thegrid-signature: 7Rp4K9mXvQ2hLwYzN8bJcT1gFdAeS6uHxI0oP3nMkWqVrCtByD5aUfGjElZiOsXm+4K8R2vN1hLwYzMbJcT6gFdA==
x-thegrid-timestamp: 1739145600
x-thegrid-fingerprint: Yk3mN7pRtV2xLwQzH8bJcS1gFdAeU6uHxI0oP3nMkWq

Request Format

  • Body: JSON-encoded request body for POST/PUT requests

  • Query Parameters: URL-encoded for GET requests

Response Headers

All API responses include the following headers:

Header
Description

x-request-id

Unique request identifier for debugging and support inquiries

x-ratelimit-limit

Maximum requests allowed in the current time window

x-ratelimit-remaining

Requests remaining in the current time window

x-ratelimit-reset

Unix timestamp when the rate limit window resets

x-ratelimit-retry-after

Seconds to wait before retrying (only present on 429 responses)

Example Response Headers:

Tip: Always include the x-request-id value when contacting support to help diagnose issues.

Response Body Format

Success Response:

Error Response:

Filtering

Many list endpoints support filtering to narrow down results. Filter parameters are passed as query parameters and vary by endpoint.

Common filter patterns:

Filter Type
Example
Description

Exact match

status=active

Returns items where field equals value

Date range

start_datetime=2024-01-01T00:00:00Z

Returns items after the specified date

Example filtered request:

See each endpoint's documentation for available filter parameters.

Sorting

List endpoints support sorting results using the order_by and order_direction parameters.

Parameter
Type
Description

order_by

string

Field to sort by. Must be one of the endpoint's sortable fields.

order_direction

string

Sort direction: asc (ascending) or desc (descending). Default: asc.

Example sorted request:

See each endpoint's documentation for available sortable fields.

Last updated

Was this helpful?