Public API

The public API lets technical implementers connect school systems to AnySchool.ai. Use it to read workspace records and create selected records from external systems, imports, or integrations.

Base URL

Use the public API host for production requests:

https://api.anyschool.ai

The API host root redirects to the main AnySchool.ai website. Resource paths continue to serve API responses.

API reference

A machine-readable OpenAPI document is available at api-reference/openapi.json.

API tokens

Workspace admins can manage API tokens from workspace settings in the API tab. Token behaviour:

Tokens are scoped to one workspace.
Only workspace admins can create, list, and revoke API tokens.
Tokens require a name and an expiry date.
The maximum expiry is two years from creation.
The full token is shown once after creation. It cannot be viewed again after closing the reveal modal.
Revoked, expired, malformed, missing, or invalid tokens return 401.

Send the token with every request:

Authorization: Bearer YOUR_TOKEN

Any valid, unexpired, unrevoked workspace API token can read and create supported records. Created records are scoped to the token workspace. Referenced IDs, such as locations, staff memberships, hazards, and excursion roles, must also belong to that workspace.

Reading records

All public GET list endpoints return a shared envelope:

{
  "data": [],
  "pagination": {
    "currentPage": 1,
    "lastPage": 1,
    "pageLength": 25,
    "numRecords": 0
  }
}

Shared query parameters:

id: Returns zero or one matching record in the same paginated envelope.
page: Positive integer. Defaults to 1.
pageLength: Positive integer. Defaults to 25, with a maximum of 100.
include: Comma-separated relationship expansions. Unsupported values return 400.
includeArchived: Optional true or false on endpoints with archived records. Defaults to false.

Public API responses use stable public shapes rather than raw database records. People endpoints expose operational identity fields and do not return date of birth by default.

Creating records

Supported POST endpoints create records only. They do not update, upsert, patch, or delete existing records. IDs are generated by AnySchool.ai, so any supplied id is ignored. Request requirements:

Content-Type: application/json
JSON object body
Maximum body size of 128 KiB
Optional Idempotency-Key header up to 255 characters

Successful creates return 201:

{
  "data": {}
}

Use Idempotency-Key when importing data or retrying requests. If the same key is reused for the same path and request body, the API replays the original successful response. If the same key is reused with a different body, the API returns 409. Write rate limits:

Default POST budget: 30 requests per minute per token.
POST /staff: 10 requests per minute per token.

Endpoints

Endpoint	Read	Create	Notes
`/excursions`	Yes	Yes	Create requires `name`. Optional schedule, location, type, activity type, educational value, non-participant plan, and `status` of `DRAFT` or `ACTIVE`.
`/students`	Yes	Yes	Create requires `firstName` and `lastName`. Optional school IDs, email, preferred name, and date of birth. Date of birth is not returned in the public DTO.
`/parents`	Yes	Yes	Create requires `firstName` and `lastName`. Optional school IDs, email, preferred name, and date of birth. Date of birth is not returned in the public DTO.
`/vendors`	Yes	Yes	Create requires `name` and `vendorType`. Optional location, notes, primary contact, and responsible staff fields.
`/locations`	Yes	Yes	Create requires `name` and `address`. Optional parent location, coordinates, metadata, external ID, and description.
`/tasks`	Yes	Yes	Create requires `title`. Optional description, status, priority, due date, assignee, role, and excursion.
`/staff`	Yes	Yes	Create invites one staff member by email and role. Existing active staff return an `ALREADY_ACTIVE` outcome.
`/groups`	Yes	Yes	Create requires `name`. Group creation does not add members.
`/risk-bank`	Yes	No	Reads the risk bank graph. Root graph writes are not supported.
`/risk-bank/groups`	Yes	Yes	Creates a standalone risk group. It is not attached as a child of another group.
`/risk-bank/hazards`	Yes	Yes	Creates a standalone hazard. It is not attached to a risk group.
`/risk-bank/controls`	Yes	Yes	Creates a control under an existing hazard.

Examples

List excursions:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.anyschool.ai/excursions?page=1&pageLength=25"

Create a student:

curl -i -X POST "https://api.anyschool.ai/students" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: student-import-001" \
  -d '{"firstName":"Ada","lastName":"Lovelace","studentEmail":"ada@example.edu"}'

Create an excursion:

curl -i -X POST "https://api.anyschool.ai/excursions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: excursion-import-001" \
  -d '{
    "name": "Museum Visit",
    "status": "DRAFT",
    "locationName": "City Museum",
    "locationAddress": "1 Museum Way",
    "departureAt": "2026-08-01T09:00:00+10:00",
    "returnAt": "2026-08-01T15:00:00+10:00"
  }'

Error responses

Public API errors use this shape:

{
  "error": {
    "code": "unauthorized",
    "message": "No valid API token was provided."
  }
}

Some validation errors include details with field-level information. Status codes:

400: Malformed query parameters, malformed JSON, missing JSON content type, invalid headers, or oversized request bodies.
401: Missing, malformed, invalid, expired, or revoked tokens.
403: Reserved for future token policy gates.
404: Production requests that do not arrive on api.anyschool.ai.
409: Idempotency-key body mismatches or duplicate conflicts.
422: Validation failures, including referenced IDs outside the token workspace.
429: Public API request budget exceeded.
500: Unexpected server errors.

Current limitations

The first public API create release does not support:

Updates, upserts, patches, or deletes.
POST /risk-bank root graph writes.
Student-parent relationship creation.
Group member creation.
Risk group child links.
Risk group hazard attachment.

Excursions

Features

Developers

Base URL

API reference

API tokens

Reading records

Creating records

Endpoints

Examples

Error responses

Current limitations

​Base URL

​API reference

​API tokens

​Reading records

​Creating records

​Endpoints

​Examples

​Error responses

​Current limitations

Base URL

API reference

API tokens

Reading records

Creating records

Endpoints

Examples

Error responses

Current limitations