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:
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
Reading records
All public GET list endpoints return a shared envelope:
{
"data": [],
"pagination": {
"currentPage": 1,
"lastPage": 1,
"pageLength": 25,
"numRecords": 0
}
}
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:
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"
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"}'
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."
}
}
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.
Last modified on June 18, 2026
