API Reference

The StudyPulse REST API gives you full programmatic access to organizations, courses, enrollments, users, and invoices. All requests return JSON and use standard HTTP methods and status codes.

Base URL https://app.studypulse.ai/api/v1

Authentication

All API requests require an API key passed in the Authorization header as a Bearer token. Generate keys from your admin dashboard under Settings → API Keys.

// Include in every request
Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxxxxx

Errors

The API uses standard HTTP status codes. Error responses include a message field and an optional code for machine-readable error types.

// 400 Bad Request
{
"error": "validation_failed",
"message": "email is required"
}

Organizations

Manage multi-tenant organizations on the platform. Super admin keys can access all organizations; org-scoped keys return only their own data.

GET /organizations List all organizations

Query parameters

Name	Type	Description
pageoptional	integer	Page number for pagination. Defaults to 1.
per_pageoptional	integer	Results per page. Max 100, default 20.
statusoptional	string	Filter by status: active, pending, suspended

Example request

cURL

curl -X GET \
  https://app.studypulse.ai/api/v1/organizations?page=1 \
  -H "Authorization: Bearer sp_live_xxxxx" \
  -H "Content-Type: application/json"

200 OK 401 Unauthorized

JSON

{
  "data": [
    {
      "id": 1,
      "name": "Northstar Academy",
      "slug": "northstar-academy",
      "status": "active",
      "sector": "school",
      "seat_count": 247,
      "created_at": "2024-09-12T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1, "per_page": 20, "total": 83
  }
}

POST /organizations/{org_slug}/enroll Enroll a learner into an organization

Path parameters

Name	Type	Description
org_slugrequired	string	The unique slug of the organization (e.g. northstar-academy)

Request body

Name	Type	Description
emailrequired	string	Learner email address. Creates a new account if not found.
first_namerequired	string	Learner's first name.
last_namerequired	string	Learner's last name.
course_idoptional	integer	Specific course ID to enroll into. Defaults to general enrollment.
billing_cycleoptional	string	monthly or yearly. Required if org has payment enabled.

Example request

cURL

curl -X POST \
  https://app.studypulse.ai/api/v1/organizations/northstar-academy/enroll \
  -H "Authorization: Bearer sp_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amara@example.com",
    "first_name": "Amara",
    "last_name": "Mensah",
    "course_id": 12,
    "billing_cycle": "monthly"
  }'

201 Created 400 Bad Request 401 Unauthorized

JSON

{
  "enrollment_id": 1842,
  "user_id": 4021,
  "org_slug": "northstar-academy",
  "course_id": 12,
  "status": "active",
  "checkout_url": null,
  "created_at": "2025-04-01T10:22:00Z"
}

GET /organizations/{org_slug}/courses List courses for an organization

Query parameters

Name	Type	Description
statusoptional	string	published or draft. Default: published.

JSON response

{
  "data": [
    {
      "id": 12,
      "title": "Introduction to Data Science",
      "status": "published",
      "lesson_count": 24,
      "enrolled_count": 148
    }
  ]
}

GET /invoices List invoices (super admin)

JSON response

{
  "data": [
    {
      "id": 1,
      "invoice_number": "SP-ORG-6-1777491974",
      "amount": 1490.00,
      "currency": "usd",
      "status": "unpaid",
      "purpose": "organization_signup",
      "created_at": "2025-04-27T14:32:00Z"
    }
  ]
}