Common API Usage

Base URL

All paths referenced for Dreams services in the API references uses the following base URL:

https://api.dreams.sa/

Versioning

https://api.dreams.sa/v1.0/

Authentication

In order to authenticate HTTP requests with an access key, you must provide it in the Authorization HTTP header with the following format. Replace <access-key> with your valid access key.

Copy

Authorization: AccessKey <access-key>

Authorization

Access key Authorization is determined by the access roles attached to your access key

Formats and Headers

All HTTP responses are in JSON. It's advised to send the Accept HTTP header with the value application/json with each request. Both POST and PUT requests to the API must contain a JSON-formatted payload in the request body.

Errors

Dreams uses standard HTTP status codes to indicate success or failure of API requests.

• HTTP response codes in the 2xx range indicate the request was successfully processed

• HTTP response codes in the 4xx range indicate that there was a client error - for example: authentication error, not enough balance or wrong/missing parameters. Don't worry, the HTTP response body includes a JSON-formatted response that tells you exactly what went wrong. If you're stuck, feel free to contact support, we're happy to help you out

• HTTP response codes in the 5xx range indicate a server error. It's considered safe to retry the same request, preferably with a delay

🔄 Pagination

Dreams APIs return paginated results when listing large sets of data. By default, results are split into pages, and you can control the number of items per page using the per_page parameter.

---

🔧 Query Parameters

Parameter	Description	Example
page	The page number to retrieve. Starts at 1.	2
per_page	The number of items per page. Maximum allowed: 100.	10

---

🧾 Response Format

Paginated responses follow this structure:

{
  "data": [
    { "id": 1, "message": "..." },
    { "id": 2, "message": "..." }
  ],
  "pagination": {
    "total": 45,
    "per_page": 10,
    "current_page": 1,
    "last_page": 5,
    "from": 1,
    "to": 10
  }
}

Each response includes:

• data: the current page's items

• pagination: a metadata block showing page info

---

▶️ Retrieving the Next Page

To fetch additional items, increment the page number in your request:

GET /v1.0/workspaces/{workspace_id}/messages/report?page=2&per_page=10

Continue requesting pages until current_page equals last_page.

---

⚠️ Notes

• The number of items returned may be fewer than per_page on the last page.

• Empty pages are possible if data was deleted between requests.

• Always use pagination.last_page to determine the end of the list.