OpenAPI Reference

The complete, machine-readable spec for the Developer API is served at:

GET https://your-kinderpedia.com/api/v1/openapi.json

No authentication required. Returns OpenAPI 3.1 JSON.

Source of truth lives at config/api/v1.openapi.yaml in the Kinderpedia codebase. The JSON endpoint converts on-the-fly and serves with appropriate cache headers.

Why expose OpenAPI

OpenAPI is the standard format that automation tools (Make.com, n8n, Postman, Insomnia, Stoplight) and code generators (openapi-generator-cli, swagger-typescript-api, etc.) read to auto-build clients.

By serving the spec from your Kinderpedia instance:

• Postman → "Import from URL" → paste the openapi.json URL → all endpoints loaded with proper auth headers.
• Make.com → "Custom API" → paste the openapi.json URL → Make builds the module structure.
• VS Code REST Client → paste the URL in .http files → autocomplete works.

Importing into Postman

1. Open Postman → File → Import.
2. Paste https://your-kinderpedia.com/api/v1/openapi.json.
3. Postman creates a Collection with all endpoints.
4. Edit the Collection's Variables tab → set baseUrl to your domain.
5. Set the Collection's Authorization to Bearer Token with your API key.
6. Click any endpoint → Send. Done.

Importing into Make.com

Make.com has built-in support for OpenAPI-driven custom modules:

1. Go to your scenario builder.
2. Add module → "HTTP" → "Make an OpenAPI 3 / Swagger Request".
3. Paste the openapi.json URL.
4. Pick the endpoint.
5. Add a connection (API key).

This is the easiest path for scenarios that need to talk to Kinderpedia.

Importing into n8n

n8n's HTTP Request node has Generic Authentication that handles Bearer tokens. There's no native OpenAPI import — instead:

1. Create an HTTP Request node.
2. Generic Credential → Header Auth → name Authorization, value Bearer kpa_live_….
3. Set method + URL based on the endpoint you want.

For more automation, the n8n-nodes-openapi community node can generate per-endpoint nodes from the spec.

What's documented

The OpenAPI spec is the authoritative list of:

• Every endpoint (path + method)
• Required and optional parameters
• Request body schemas
• Response body schemas (200, 201, 400, 401, 404, 422 etc.)
• Authentication schemes
• Rate-limit headers
• Idempotency-Key header behaviour

If a behaviour isn't in the spec, it's not part of the public API contract — assume it can change.

Endpoint summary

Path	Methods	Purpose
/whoami	GET	Identity check
/leads	GET, POST	List + create
/leads/{id}	GET, PUT	Read + update
/leads/{id}/archive	POST	Archive (recoverable)
/leads/{id}/unarchive	POST	Restore
/leads/{id}/transition	POST	Move to a new stage
/leads/{id}/notes	GET, POST	Notes
/leads/{id}/activities	GET, POST	Activities
/leads/{id}/activities/{aid}/complete	POST	Mark activity done
/pipelines	GET	List pipelines
/stages	GET	List stages
/applicant-statuses	GET	List applicant status settings
/forms	GET	List forms

Full schemas, examples, and error responses are in the spec itself.

Schema patterns

A few conventions you'll see repeatedly:

Public field names

Most resource schemas use simplified field names that differ from DB columns:

Public field	DB column
email	student_email
phone	student_phone
is_applicant	derived from roster_type
parent_email	from linked parents.email

The OpenAPI spec documents the public name. Your client should never need to know the DB column.

Cursor pagination

List responses always include:

• A JSON array of items (no envelope object)
• A Link header with the next URL when more pages exist
• No total_count or has_more fields — pagination is opaque

Example response headers:

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://.../leads?after=eyJpZCI6MTczfQ&limit=50>; rel="next"

Date format

All timestamps are ISO-8601 with timezone:

"created_at": "2026-05-12T14:32:18+00:00"

We always send UTC offsets. Your client should parse them naturally with any standard ISO-8601 parser.

Error format

All errors:

{
  "error": "validation_failed",
  "message": "Field 'parent_email' must be a valid email address.",
  "details": { "field": "parent_email" }
}

error is a stable machine-readable code. message is human-readable (English only currently). details is optional, error-specific extra data.

Tutorial: lead creation end-to-end

KEY="kpa_live_…"
KP="https://your-kinderpedia.com"

# 1. Verify auth
curl -H "Authorization: Bearer $KEY" $KP/api/v1/whoami

# 2. List available forms (so you can pick a form_id)
curl -H "Authorization: Bearer $KEY" $KP/api/v1/forms

# 3. Create a lead idempotently
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "student_name": "Anna Smith",
    "parent_name": "Bob Smith",
    "parent_email": "[email protected]",
    "parent_phone": "+15551234567",
    "form_id": 1
  }' \
  $KP/api/v1/leads

# 4. Add a note to the new lead (use the id returned from step 3)
LEAD_ID=4321
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"body": "First contact via Make.com"}' \
  $KP/api/v1/leads/$LEAD_ID/notes

# 5. Transition to a different stage
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"to_stage_id": 7}' \
  $KP/api/v1/leads/$LEAD_ID/transition

Spec changes

Backward-compatible additions (new endpoints, new optional fields, new response fields) happen freely on v1 — your client should be tolerant of unknown response fields.

Breaking changes (renaming fields, removing endpoints, changing required → optional or vice versa) will move to v2. v1 will get at least 12 months of support after v2 ships.

Reporting issues

If you find a mismatch between the spec and the actual API behaviour, report it. The spec is supposed to be authoritative — divergence is a bug.

Related

• API keys
• Webhooks
• Rate limits and idempotency
• Developer API overview