Your First API Request

Learn the request format, response structure, and common patterns for the Olympus Cloud REST API.

Base URL

Environment	Base URL
Development	https://dev.api.olympuscloud.ai/v1
Staging	https://staging.api.olympuscloud.ai/v1
Production	https://api.olympuscloud.ai/v1

The API version (v1) is included in the URL path.

---

Step 1: Get a JWT Token

First, log in to obtain an access token:

TOKEN=$(curl -s -X POST https://dev.api.olympuscloud.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "manager@demo-restaurant.com",
    "password": "DevPassword123!"
  }' | jq -r '.status.access_token')

---

Step 2: Browse a Public Endpoint

Some endpoints don't require authentication. Restaurant menus are public:

curl -s https://dev.api.olympuscloud.ai/v1/restaurants/550e8400-e29b-41d4-a716-446655449110/menu | jq .

---

Step 3: Call an Authenticated Endpoint

Create an order (requires JWT):

curl -s -X POST https://dev.api.olympuscloud.ai/v1/commerce/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "550e8400-e29b-41d4-a716-446655449110",
    "source": "pos",
    "currency": "USD",
    "items": [
      {"menu_item_id": "ITEM_UUID", "name": "Margherita Pizza", "quantity": 1, "unit_price": 14.99}
    ]
  }' | jq .

---

Step 4: Check Order Status

curl -s https://dev.api.olympuscloud.ai/v1/commerce/orders/ORDER_UUID \
  -H "Authorization: Bearer $TOKEN" | jq .

---

Request Format

Required Headers

Header	Required	Description
Authorization	Yes (authenticated routes)	Bearer <jwt_token>
Content-Type	Yes (POST/PUT/PATCH)	application/json

Optional Headers

Header	Description
X-Request-ID	Unique request identifier for tracing
X-Idempotency-Key	Prevent duplicate operations (recommended for POST)

Tenant Context

Tenant context is embedded in the JWT token — you don't need to pass a separate X-Tenant-ID header. The API gateway extracts the tenant from your token automatically.

---

Response Format

Success Responses

Responses are JSON. The structure varies by endpoint — most return the resource object directly:

{
  "id": "550e8400-...",
  "status": "pending",
  "source": "pos",
  "currency": "USD",
  "total": 14.99,
  "created_at": "2026-02-19T12:30:00Z"
}

HTTP Status Codes

Code	Meaning
200	OK — successful GET, PUT, PATCH
201	Created — successful POST
204	No Content — successful DELETE
400	Bad Request — malformed JSON or missing required fields
401	Unauthorized — missing, expired, or invalid JWT
403	Forbidden — valid token but insufficient role
404	Not Found — resource doesn't exist or not in your tenant
422	Unprocessable Entity — business logic validation failed
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — retry after a moment

---

Error Response Format

Errors return a standard JSON object from the API gateway:

{
  "error": "VALIDATION_ERROR",
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": {
    "items[0].quantity": "must be greater than 0"
  },
  "request_id": "req-abc123-def456",
  "timestamp": "2026-02-19T12:30:00Z"
}

Common Error Codes

Code	HTTP Status	Description
BAD_REQUEST	400	Malformed request
VALIDATION_ERROR	400	Invalid request data
UNAUTHORIZED	401	Missing or invalid token
TOKEN_EXPIRED	401	JWT token expired
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
TOO_MANY_REQUESTS	429	Rate limit exceeded

See the Error Handling guide for the complete list.

---

Rate Limiting

The API gateway enforces rate limits. When exceeded:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 80
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708372800

The default rate limit is 80 requests per second per IP address.

Implement exponential backoff for retries.

---

Idempotency

For POST requests, use X-Idempotency-Key to prevent duplicate resource creation on retries:

curl -X POST https://dev.api.olympuscloud.ai/v1/commerce/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: create-order-abc123" \
  -d '{"source": "pos", "currency": "USD", "items": [...]}'

---

What's Next?

• REST API Examples — Full examples in curl, Python, JavaScript, and Go
• API Reference — Complete endpoint documentation
• Error Handling — Detailed error handling guide

---

Related Documentation

• Quickstart — End-to-end getting started
• Authentication — JWT auth flow
• API Reference — Full API documentation