API Overview

The Sessiq API provides programmatic access to all platform features, allowing you to integrate booking functionality into your own applications.

Base URL

The API base URL depends on your environment:

Production: https://api.sessiq.com/api/v1
Staging: https://staging.api.sessiq.com/api/v1
Development: http://localhost:3001/api/v1

All endpoints are versioned under /api/v1.

Authentication

All API requests require authentication using JWT (JSON Web Token) Bearer tokens. The only exception is the public availability endpoint.

Authentication Headers

Every authenticated request must include:

Authorization: Bearer <your-jwt-token>
x-tenant-id: <your-tenant-id>
Content-Type: application/json

Obtaining a Token

To obtain an authentication token, use the login endpoint:

POST /api/auth/login
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password",
  "tenantId": "your-tenant-id"
}

The response includes an access_token that should be used in subsequent requests:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "username": "your-username",
    "tenant_id": "t_demo",
    "roles": ["admin"],
    "permissions": ["bookings:read", "bookings:write"]
  }
}

Token Expiration

Tokens typically expire after 1 hour. When a token expires, you'll receive a 401 Unauthorized response. Re-authenticate using the login endpoint to obtain a new token.

Tenant Context

The x-tenant-id header is required for all requests (except login) to ensure proper data isolation in the multi-tenant system. The tenant ID should match the tenant associated with your authentication token.

API Endpoints Overview

The API is organized into logical groups:

Availability

GET /availability - Query available time slots for a product
GET /availability/products/:productId/addons - Get available add-ons for a product
GET /availability/sites/:siteId/config - Get site frontend configuration (GTM container ID)

Bookings

POST /bookings/hold - Create a temporary booking hold
POST /bookings/{id}/confirm - Confirm a booking and process payment
GET /bookings/{id} - Get booking details
POST /bookings/{id}/cancel - Cancel a booking
POST /bookings/{id}/reschedule - Reschedule a booking to a new time
POST /bookings/{id}/apply-promo - Apply a promotion code to a booking
POST /bookings/{id}/apply-voucher - Apply a voucher code to a booking
PATCH /bookings/{id}/mark-no-show - Mark a booking as no-show

Payments

POST /payments/authorize - Authorize a payment
POST /payments/capture - Capture an authorized payment
POST /payments/refund - Process a refund
POST /webhooks/stripe - Stripe webhook endpoint
POST /webhooks/paytrail/callback - Paytrail webhook endpoint

Promotions

POST /promotions/validate - Validate a promotion code
POST /promotions/apply - Apply a promotion to a cart
GET /promotions - List available promotions

Images

POST /admin/images/products/:productId - Upload image to product (multipart/form-data)
GET /admin/images/products/:productId - Get all images for a product
DELETE /admin/images/:imageId - Delete an image
PATCH /admin/images/products/:productId/reorder - Reorder product images
GET /availability/products/:productId/images - Get product images (public)

Admin APIs

Admin endpoints require additional permissions. See individual endpoint documentation for required permissions.

Catalog management (products, variants, resources, schedules)
Calendar operations (drag-and-drop rescheduling)
Reporting endpoints
Resource maintenance scheduling
Image management (upload, delete, reorder)

Resource Groups

GET /admin/resource-groups - List all resource groups
GET /admin/resource-groups/:id - Get resource group details
POST /admin/resource-groups - Create a resource group
PATCH /admin/resource-groups/:id - Update a resource group
DELETE /admin/resource-groups/:id - Delete a resource group
GET /admin/resource-groups/:id/resources - Get resources in a group
POST /admin/resource-groups/assign - Assign resource to group
POST /admin/resource-groups/assign/bulk - Bulk assign resources
DELETE /admin/resource-groups/unassign/:resourceId - Unassign resource from group
PATCH /admin/resource-groups/:id/policies - Update group policies
GET /admin/resource-groups/resources/:resourceId/effective-policies - Get effective policies

Staff Skills

GET /admin/skills - List all skills
GET /admin/skills/:id - Get skill details
POST /admin/skills - Create a skill
PATCH /admin/skills/:id - Update a skill
DELETE /admin/skills/:id - Delete a skill
POST /admin/skills/assign - Assign skill to resource
POST /admin/skills/assign/bulk - Bulk assign skills to resource
DELETE /admin/skills/resources/:resourceId/skills/:skillId - Remove skill from resource
GET /admin/skills/resources/:resourceId - Get skills for a resource
POST /admin/skills/products/:productId/requirements - Add skill requirement to product
GET /admin/skills/products/:productId/requirements - Get product skill requirements
GET /admin/skills/expiring - Get skills expiring soon
GET /admin/skills/availability - Check resources with required skills

Sandbox Mode

POST /admin/tenants/sandbox/toggle - Toggle sandbox mode
GET /admin/tenants/sandbox/status - Get sandbox mode status

Auto-Reschedule

GET /admin/reschedule/suggestions - List pending reschedule suggestions
POST /admin/reschedule/suggestions/:id/approve - Approve reschedule
POST /admin/reschedule/suggestions/:id/reject - Reject reschedule
POST /reschedule/:token/accept - Customer accepts reschedule (public)
POST /reschedule/:token/decline - Customer declines reschedule (public)

Response Format

Success Responses

Successful API responses typically follow this structure:

{
  "data": {
    // Response data specific to the endpoint
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Some endpoints may return data directly (e.g., availability endpoint returns slots array).

Error Responses

Errors are returned with appropriate HTTP status codes and follow this format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "code": 400,
  "details": {
    // Additional error context
  }
}

Common HTTP status codes:

200 OK - Success
201 Created - Resource created successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required or token expired
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
409 Conflict - Business rule violation (e.g., pricing changed, slot unavailable)
422 Unprocessable Entity - Validation error
500 Internal Server Error - Server error

Error Codes

Common error codes you may encounter:

BOOKING_NOT_FOUND - The specified booking doesn't exist
SLOT_UNAVAILABLE - The requested time slot is no longer available
PRICING_CHANGED - Pricing has changed since the hold was created
OUTSIDE_WINDOW - Request is outside allowed policy window
INVALID_PROMOTION - Promotion code is invalid or not applicable
INSUFFICIENT_PERMISSIONS - User lacks required permissions
VALIDATION_ERROR - Request validation failed

Rate Limiting

API requests are rate-limited to ensure system stability. Rate limits vary by endpoint category.

Rate Limit Tiers

Tier	Endpoints	Limit	Window
Strict	`/auth/login`, `/auth/register`, `/customers/auth/*`	5 requests	60 seconds
Standard	Most authenticated endpoints	100 requests	60 seconds
Relaxed	`/availability/*`, public read endpoints	200 requests	60 seconds

Response Headers

All responses include rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when window resets

Rate Limited Response

When rate limited, you'll receive a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642248000
Content-Type: application/json

{
  "statusCode": 429,
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60
}

Best Practices

Implement exponential backoff when receiving 429 responses
Cache responses where appropriate to reduce API calls
Use the Retry-After header to schedule retries

Best Practices

Request Headers

Always include the required headers and use consistent Content-Type:

Authorization: Bearer <token>
x-tenant-id: <tenant-id>
Content-Type: application/json
Accept: application/json

Error Handling

Implement proper error handling:

Check HTTP status codes
Parse error responses for user-friendly messages
Handle token expiration gracefully
Retry with exponential backoff for transient errors

Idempotency

For payment and booking operations, use idempotency keys to prevent duplicate processing:

POST /api/v1/bookings/hold
Idempotency-Key: unique-request-id-12345

Pricing Hash Validation

When confirming bookings, always validate the pricing hash to ensure pricing hasn't changed:

{
  "bookingId": "booking_123",
  "pricingHash": "abc123...",
  "paymentMethodId": "pm_xyz"
}

If pricing has changed, you'll receive a 409 Conflict with PRICING_CHANGED error code.

Pagination

List endpoints support pagination. Use query parameters:

GET /api/v1/bookings?page=1&limit=20

Next Steps

Learn about Authentication in detail
Explore Availability API for querying slots
Review Bookings API for booking operations
Check out Payments API for payment processing

Base URL​

Authentication​

Authentication Headers​

Obtaining a Token​

Token Expiration​

Tenant Context​

API Endpoints Overview​

Availability​

Bookings​

Payments​

Promotions​

Images​

Admin APIs​

Resource Groups​

Staff Skills​

Sandbox Mode​

Auto-Reschedule​

Response Format​

Success Responses​

Error Responses​

Error Codes​

Rate Limiting​

Rate Limit Tiers​

Response Headers​

Rate Limited Response​

Best Practices​

Best Practices​

Request Headers​

Error Handling​

Idempotency​

Pricing Hash Validation​

Pagination​

Next Steps​

Base URL

Authentication

Authentication Headers

Obtaining a Token

Token Expiration

Tenant Context

API Endpoints Overview

Availability

Bookings

Payments

Promotions

Images

Admin APIs

Resource Groups

Staff Skills

Sandbox Mode

Auto-Reschedule

Response Format

Success Responses

Error Responses

Error Codes

Rate Limiting

Rate Limit Tiers

Response Headers

Rate Limited Response

Best Practices

Best Practices

Request Headers

Error Handling

Idempotency

Pricing Hash Validation

Pagination

Next Steps