Integration API

Build on contracts
you can reason about.

This is the starting point for Schoolbooks integrations: versioned URLs, predictable errors, request correlation, and an honest view of what is live versus planned.

Overview

A small, stable surface before a large one.

The API currently exposes the operational foundation used to run and observe Schoolbooks. Accounting and school-management resources will only appear here after their tenancy, authorization, and idempotency contracts are approved.

Versioned by default

Public routes begin at /api/v1. Breaking contract changes require a new version.

Tenant-safe by design

Future domain routes will derive tenant context from trusted identity claims—not caller-supplied schema names.

Predictable failures

API errors use an RFC 9457-style problem document and carry the same request ID as server logs.

Quickstart

Make one request with no credentials.

The liveness probe confirms that the API process can answer a request. It deliberately does not test PostgreSQL or storage.

Base URLhttps://api.schoolbooks.ke/api/v1
Environment-specific
cURL
curl --request GET \
  --url https://api.schoolbooks.ke/api/v1/health/live \
  --header 'accept: application/json' \
  --header 'x-request-id: integration-check-001'
200 · application/json
{
  "environment": "production",
  "message": "Application process is running.",
  "service": "schoolbooks-api",
  "status": "ok",
  "timestamp": "2026-07-31T09:30:00.000Z",
  "uptimeSeconds": 3600,
  "version": "0.0.0"
}

Live now

Operational endpoints.

These routes are unauthenticated, excluded from throttling, and fully described in the generated OpenAPI document.

GET
/health/live

Process liveness without calling dependencies.

200
GET
/health/ready

PostgreSQL, memory, public assets, and upload-storage readiness.

200 · 503
GET
/health

Detailed dependencies and bounded recent runtime diagnostics.

200 · 503

Coming next

Domain APIs will arrive contract-first.

These resource families describe the intended integration surface. They are not live endpoints yet. Each will ship with schemas, authorization rules, examples, idempotency behavior, and tenant-isolation tests.

Payments

Planned

Receive transaction events and retrieve reconciliation state.

Fees and balances

Planned

Read approved fee structures, invoices, allocations, and balances.

Learner references

Planned

Resolve stable integration identifiers without exposing unnecessary records.

Webhooks

Planned

Subscribe to versioned, signed events with delivery history and retries.

Authentication contract pending

An identity provider has not been selected. We will not publish an API-key or OAuth flow until tenant claims, service accounts, rotation, and revocation are designed together.

Until then, use the unauthenticated health routes only. Do not build production domain integrations against placeholder credentials.

Errors and request IDs

One shape, one correlation trail.

Send a valid x-request-id when you already have a correlation ID. Otherwise Schoolbooks creates one. The response header, problem document, and server logs use the same value.

application/problem+json
{
  "type": "https://schoolbooks.app/problems/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "instance": "/api/v1/example",
  "code": "RESOURCE_NOT_FOUND",
  "requestId": "40bf7ef8-a812-4f02-953e-6fd7bfe24c01",
  "timestamp": "2026-07-31T09:30:00.000Z"
}

Accepted request IDs

  • At most 128 characters.
  • Letters, numbers, dot, underscore, colon, and hyphen only.
  • Returned in the x-request-id response header.