Skip to main content

Overview and Authorization

Overview​

Stack9 Experience API provides comprehensive endpoints for managing content, marketing, and AI services. This RESTful API enables developers to integrate with Stack9's Digital Experience Platform (DXP) to manage email campaigns, content pages, forms, AI assistants, and more.

Base URL​

https://apis.app.stack9.co/api

For development environments:

http://localhost:3000/api

Authentication​

All API requests require authentication using an API key. Include your API key in the request headers:

X-API-Key: your-api-key-here

Example Request with Authentication​

curl -X GET \
  https://apis.app.stack9.co/api/email_settings \
  -H 'X-API-Key: your-api-key-here' \
  -H 'Content-Type: application/json'

Request Format​

  • All requests must include the Content-Type: application/json header
  • Request bodies should be valid JSON
  • Path parameters are denoted with curly braces in the endpoint documentation
  • Query parameters should be URL-encoded

Response Format​

All API responses follow a consistent JSON structure:

Successful Response​

{
  "results": [...],
  "metadata": {
    "total": 100,
    "page": 1,
    "pageSize": 20
  }
}

Error Response​

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {}
  }
}

HTTP Status Codes​

Status CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
204No Content - Request succeeded with no response body
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource not found
409Conflict - Resource conflict (e.g., duplicate)
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error

Rate Limiting​

API requests are rate-limited to ensure service stability:

  • Standard tier: 100 requests per minute
  • Premium tier: 1000 requests per minute
  • Enterprise tier: Custom limits

Rate limit headers are included in all responses:

  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Unix timestamp when the window resets

Pagination​

List endpoints support pagination using the following parameters:

ParameterTypeDefaultDescription
pageinteger1Page number (1-based)
pageSizeinteger20Number of items per page (max: 100)
sortBystringcreated_atField to sort by
sortOrderstringdescSort direction (asc/desc)

Pagination Response​

{
  "results": [...],
  "metadata": {
    "total": 250,
    "page": 2,
    "pageSize": 20,
    "totalPages": 13,
    "hasNext": true,
    "hasPrevious": true
  }
}

Filtering and Searching​

Many list endpoints support filtering and searching:

Filter Syntax​

GET /api/subscribers?status=active&created_after=2024-01-01

Search Syntax​

GET /api/subscribers/search?q=john@example.com

Webhooks​

Stack9 Experience supports webhooks for real-time event notifications. Configure webhooks through the Email Settings API to receive notifications for:

  • Email delivery events
  • Form submissions
  • Subscriber status changes
  • Campaign completion

API Versioning​

The API version is included in the response headers:

X-API-Version: 1.7.4

Breaking changes will be introduced in new major versions with advance notice.

SDK and Libraries​

Official SDKs are available for:

  • JavaScript/TypeScript
  • Python
  • PHP
  • Ruby
  • Go

Support​

For API support:

Quick Start Guide​

  1. Obtain API Credentials: Contact your Stack9 administrator to get API keys
  2. Test Authentication: Make a test request to /api/email_settings
  3. Explore Endpoints: Review the resource-specific documentation
  4. Implement Integration: Use our SDKs or make direct HTTP requests
  5. Monitor Usage: Track your API usage through the dashboard

Resource Documentation​

Detailed documentation for each resource type: