API & Developer Documentation

Developer resources for integrating with and building on the Skoolyst platform.

Documentation Being Prepared

Full developer API documentation for the Skoolyst platform is still being prepared. One real, live API is already documented below — Skoolyst Ads — and more endpoints will be added here as other Skoolyst applications expose their own APIs.

Skoolyst Ads API

Skoolyst Ads (ads.skoolyst.com) is the first Skoolyst application with a real, public API. It lets a connected app request an eligible ad for one of its own placements. Full guide: Skoolyst Ads.

# Get an ad for a placement

## Description
Returns one eligible ad for the requesting app's given placement, or
null if nothing currently qualifies.

## Request
- Method: GET
- URL: /api/v1/ads/serve
- Headers: Authorization: Bearer <connected-app-api-key>
- Query: placement=<placement-code>

## Response
Status: 200 OK
Content-Type: application/json

{
  "success": true,
  "data": {
    "ad": {
      "id": 1,
      "title": "Speak Confidently in 8 Weeks",
      "description": "Small group classes",
      "image_path": "/uploads/ads/example.jpg",
      "cta_text": "Book Now",
      "click_url": "https://example.com/enroll"
    }
  }
}

## Errors
| Status | Description                   |
|--------|--------------------------------|
| 401    | Missing or invalid API key    |
| 404    | Unknown app or placement code |

Every connected app authenticates with its own API key, generated and, if needed, regenerated from Admin → Connected Apps. There is no shared/global key — one app's key can be revoked without affecting any other app's integration.

Planned Documentation Sections

The following sections will be documented as more of the Skoolyst API is developed:

API Overview

Introduction to the Skoolyst API, its architecture and capabilities.

Authentication

How to authenticate API requests using API keys and tokens.

Endpoints

Complete reference of available API endpoints and methods.

Request / Response

Request formats, response structures and data types.

API Keys

How to generate, manage and revoke API keys.

Webhooks

Subscribe to platform events via webhook notifications.

Errors

Error codes, error response format and troubleshooting.

Rate Limits

Rate limiting policies, headers and best practices.

SDKs

Official software development kits for popular languages.

Documentation Template

When API documentation is added, it will follow a structure similar to this:

# Endpoint Name

## Description
Brief description of what this endpoint does.

## Request
- Method: GET / POST / PUT / DELETE
- URL: /api/v1/resource
- Headers: Authorization: Bearer <token>

## Parameters
| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| id        | string | Yes      | Resource ID |

## Response
Status: 200 OK
Content-Type: application/json

{
  "data": { ... },
  "status": "success"
}

## Errors
| Status | Code         | Description           |
|--------|------------- |-----------------------|
| 400    | bad_request  | Invalid parameters    |
| 401    | unauthorized | Authentication failed |
| 404    | not_found    | Resource not found    |

This template is for illustration only, beyond the real Skoolyst Ads API documented above.