Overview
Connect to your authorized workspace.
Schoolbooks provides operational endpoints, authenticated domain APIs, and a scoped MCP endpoint for compatible agents. Consult live OpenAPI schemas and discovered tools for the available contracts.
Versioned by default
Public routes begin at /api/v1. Breaking contract changes require a new version.
Tenant-safe by design
Integration keys bind a user, account, workspace and organization. Callers cannot choose a schema or override scope.
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.
https://api.schoolbooks.ke/api/v1curl --request GET \
--url https://api.schoolbooks.ke/api/v1/health/live \
--header 'accept: application/json' \
--header 'x-request-id: integration-check-001'{
"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.
/health/liveProcess liveness without calling dependencies.
200/health/readyPostgreSQL, memory, public assets, and upload-storage readiness.
200 · 503/healthDetailed dependencies and bounded recent runtime diagnostics.
200 · 503Agent integrations
Connect Codex through MCP.
Read the complete MCP connection guide for prerequisites, SDK setup, scope checks and troubleshooting, or start with Spark inside Schoolbooks.
Create an expiring key in Settings → Security → API keys in the intended workspace. Start with accounts.read, workspaces.read and only the domain permissions you need, such as accounting.read. The key remains bound to its owner, account, workspace and organization, with live access checks on every request.
Register the Streamable HTTP endpoint:
codex mcp add schoolbooks --url https://api.schoolbooks.ke/api/v1/mcp Merge this configuration into the existing schoolbooks entry in ~/.codex/config.toml; do not duplicate the table:
[mcp_servers.schoolbooks]
url = "https://api.schoolbooks.ke/api/v1/mcp"
env_http_headers = { "X-API-Key" = "SCHOOLBOOKS_API_KEY" } Set SCHOOLBOOKS_API_KEY through your secret manager or environment before starting Codex. Keep the key out of URLs, source control and chat. Use /mcp in Codex to inspect the connection, then ask the agent to read schoolbooks://context/current and confirm its scope.
This endpoint requires X-API-Key. Do not use --bearer-token-env-var or codex mcp login: OAuth-only hosts are not supported. Available tools depend on the key's permissions, enabled modules and subscription. Financial posting and approval restrictions remain enforced; MCP does not grant unrestricted writes.
For local development use http://localhost:3001/api/v1/mcp. Hosted use requires the MCP release and platform migrations to be deployed. A 401 indicates missing, invalid, expired or revoked credentials; 403 indicates access or origin restrictions. Replace a key by creating another scoped key in Security settings, updating the integration and revoking the old key. Revoke a compromised key immediately. An MCP tool error can arrive with HTTP 200; inspect isError rather than assuming success.
See the official Codex MCP configuration for custom HTTP headers.
Coming next
Additional integration surfaces.
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.
Webhooks
Subscribe to versioned, signed events with delivery history and retries.
Scoped API-key authentication
Expiring integration keys support explicit permissions, rotation and revocation. The authorized user and workspace determine account and organization scope.
Create and manage keys through your signed-in Security settings. An agent cannot issue credentials or approve its own actions. Check each OpenAPI operation and discovered MCP tool for its supported authentication and permissions.
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.
{
"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-idresponse header.