Admit Protocol · specification · draft 0.1-draft
The specification
Transport is plain HTTPS with JSON, plus an MCP server exposing the same operations. Every school serves these under its own base address; on the hosted service that is admitprotocol.com/<school>. A school's live schema is authoritative; this page describes the common shape.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /skill.md | What an agent reads first: the school's rules, prompts and the flow, in plain words. |
| GET | /v1/schema | The fields, enums, item types, writing prompts and checklist the school enforces, as JSON Schema. |
| POST | /v1/applications | Start. The school emails a 6-digit code to the parent or guardian. |
| POST | /v1/applications/{id}/verify | Prove the parent's email. Returns an application token. |
| POST | /v1/applications/{id}/resend | Send a new code. |
| PATCH | /v1/applications/{id} | Change fields other than the verified parent. |
| POST | /v1/applications/{id}/items | Add a text item, such as the student's writing with its attestation and prompt key. |
| POST | /v1/applications/{id}/items/file | Add a file: PDF, JPG, PNG, HEIC or DOCX, 20 MB. |
| POST | /v1/applications/{id}/requests | Ask the school to contact a recommender or a registrar. |
| GET | /v1/applications/{id} | The checklist: received, missing, reviewed, which prompts are answered, and the next action. |
| POST | /v1/applications/{id}/submit | Hand the application to the school. |
| POST | /v1/applications/{id}/withdraw | Withdraw. |
| MCP | /mcp | The same operations as tools, for clients with connector support. |
| MCP | https://admitprotocol.com/mcp | The platform server: one connector for every school. list_schools, get_school_instructions, then the same tools with a `school` argument. |
One connector for every school
A family that has not chosen a school yet, or a client that can hold only one connector, uses the platform server at admitprotocol.com/mcp. It lists the schools on the protocol, returns any school's skill file and schema, and exposes the application tools with a school argument naming the slug. Validation uses that school's live schema. Tokens are still per school and per application. A school's own server at its base address remains the canonical one; the platform server is a convenience for discovery.
Authentication
Starting an application needs nothing. Everything after verification sends Authorization: Bearer <application_token>, a token scoped to one application and one school, stored by the agent in the family's folder under .admit-protocol/. Codes expire in minutes and work once; tokens last about three months.
Common application fields
parent (name, email, relationship), student (names, date of birth, current school and grade, place, languages at home, international), entering_year, entering_grade, boarding_or_day, and an agent block naming the client. Schools may add fields; they should not remove these.
Item types
Family-sent: writingparent_statementtranscriptreport_cardtest_scoreenglish_competencyiep_504awardsadditional. Requested by the school, never sent by the family: recommendation_mathrecommendation_englishrecommendation_counselorrecommendation_personal.
Writing prompts and attestation
A school lists its prompts in the schema, each with a key, an optional word range, an optional "choose one" group and a required flag. Each answer is a writing item naming its prompt. A server must refuse a writing item whose attestation differs from:
{ "type": "writing", "prompt": "reading", "text": "...",
"attestation": { "written_by": "student", "agent_edited": false, "confirmed_by": "parent" } }Checklist
Status responses carry a checklist whose step names mirror the school's own system. Each step is missing, received, reviewed, waived or school (scheduled by the school). The reference steps:
- * Application · family
- * Student writing · family
- Parent Statement · family
- Transcripts · family
- Educational Testing · family
- English Competency Testing (TOEFL/IELTS) · family
- IEP/504 Documents · family
- Additional Information · family
- Mathematics Recommendation · recommender
- English Recommendation · recommender
- Principal/Counselor Recommendation · recommender
- Personal Recommendation · recommender
- Campus Tour · school
- Interview · school
Errors
400 with a list of rejected fields, 401 for a missing or expired token, 409 for a state conflict, 413 for a file over the limit, 429 for too many requests. Bodies are { "error": "plain words", "details": [...] }.
Status of this document
Draft 0.1-draft, November 2026. The reference implementation is the hosted service; Verde Valley School is the first school on it. Breaking changes bump the version in /v1/schema; a school's skill file is the contract an agent follows when the two disagree.
The specification text, JSON Schemas, a conformance checklist and an example skill file are public at github.com/Admit-Protocol/Admit-Protocol (text CC BY 4.0, schemas and code MIT). Propose changes there.