OpenAPI Spec & Postman Collection

If you want a machine-readable contract — every endpoint with its request/response fields and data types — use the OpenAPI spec below instead of reading the prose guides. It powers Postman, Insomnia, Swagger UI, and client-code generators.

Download links

Add ?download=1 to either URL to force a file download instead of viewing it in the browser.

Import into Postman

Option A — import the OpenAPI spec (recommended, always current):

1. Postman → Import → Link.
2. Paste https://www.preparebuddy.com/assessment/api/openapi.json → Continue → Import.
3. Postman generates a collection with every endpoint, folder, and example body.
4. Open the collection's Variables and set:
5. baseUrl → https://www.preparebuddy.com
6. Add an Authorization header on the collection: X-API-Key = your key (from Evaluation Studio → API keys).

Option B — import the ready-made Postman collection:

1. Postman → Import → Link → paste https://www.preparebuddy.com/assessment/api/postman_collection.json.
2. Open the collection's Variables tab and set:
3. base_url = https://www.preparebuddy.com
4. api_key = your API key.
5. Every request already sends X-API-Key: {{api_key}} and has an example JSON body you can edit.

View as interactive docs (Swagger UI)

Paste the OpenAPI URL into any Swagger UI / Redoc viewer (e.g. https://editor.swagger.io/ → File → Import URL) to browse the schemas interactively.

What's in the spec

• Auth schemes: X-API-Key header (recommended) or Authorization: Bearer <token>.
• All endpoints grouped by resource: Authentication, Organizations, Rubrics, Reference Examples, Feedbacks, Batches, Reports, Email.
• Every field's type, whether it's required, allowed enum values, and defaults — e.g. quality_level ∈ excellent | good | average | poor, criterion_type ∈ score | binary | count | percentage, batch status ∈ pending | processing | completed | failed.
• Each criterion's performance_levels — the four bands (excellent, good, satisfactory, needs_improvement) with their point ranges and descriptions, returned on every rubric GET and settable on create/update.
• The shared error envelope ({ success, code, error }) and the full list of error codes.

The spec is the source of truth for field names and types. The API Quickstart walks through the same endpoints step by step with copy-paste examples.