> ## Documentation Index > Fetch the complete documentation index at: https://docs.classquill.com/llms.txt > Use this file to discover all available pages before exploring further. # Recommend Tutors > Rank the org's tutors for a booking request, best fit first. Each tutor is scored 0–100 on subject match, availability overlap with the requested days/times, teaching mode, spare capacity, and — for an in-person request with a known suburb — proximity (via the shared match_org_tutors RPC, which also powers the in-app matcher). Tutors who can't do the requested arrangement or are beyond their travel radius are omitted. Includes a per-signal `breakdown`, `distance_km`/`nearby`, and human-readable `reasons`. Read-only — this recommends, it never assigns. 404 if the request isn't this org's. ## OpenAPI ````yaml /openapi.json get /v1/booking-requests/{request_id}/recommended-tutors openapi: 3.1.0 info: title: ClassQuill Public API description: >- REST API for ClassQuill tutoring organisations. Pipe your sessions, invoices, payments, tutor earnings, students, and more into your own tools. Most endpoints are reads; a focused set of writes (each gated by a *:write scope) create or update data, including creating student/tutor/parent accounts. Authenticate every request with an org API key: Authorization: Token token=cq_live_... Mint keys in the ClassQuill app under Settings → Developers. version: 1.0.0 servers: [] security: - ApiKeyAuth: [] tags: - name: General - name: Sessions - name: Tutors - name: Students & Parents - name: Billing - name: Curriculum - name: Coursework - name: Operations - name: Pricing - name: Bookings - name: Blog - name: Reports paths: /v1/booking-requests/{request_id}/recommended-tutors: get: tags: - Bookings summary: Recommend Tutors description: >- Rank the org's tutors for a booking request, best fit first. Each tutor is scored 0–100 on subject match, availability overlap with the requested days/times, teaching mode, spare capacity, and — for an in-person request with a known suburb — proximity (via the shared match_org_tutors RPC, which also powers the in-app matcher). Tutors who can't do the requested arrangement or are beyond their travel radius are omitted. Includes a per-signal `breakdown`, `distance_km`/`nearby`, and human-readable `reasons`. Read-only — this recommends, it never assigns. 404 if the request isn't this org's. operationId: recommend_tutors_v1_booking_requests__request_id__recommended_tutors_get parameters: - name: request_id in: path required: true schema: type: string description: Booking request UUID title: Request Id description: Booking request UUID - name: limit in: query required: false schema: type: integer maximum: 50 minimum: 1 description: Max tutors to return (default 10, max 50) default: 10 title: Limit description: Max tutors to return (default 10, max 50) responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/RecommendedTutors' '401': description: Missing, malformed, revoked, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: The credential lacks the scope this endpoint requires. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: >- Not found — the record doesn't exist or belongs to another organisation. content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: Validation error — `error.details.errors` lists the fields. content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: >- Rate limit exceeded — honour Retry-After and the RateLimit-* headers. content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: RecommendedTutors: properties: request_id: type: string title: Request Id subject_id: anyOf: - type: string - type: 'null' title: Subject Id data: items: $ref: '#/components/schemas/RecommendedTutor' type: array title: Data type: object required: - request_id - data title: RecommendedTutors ApiError: description: Canonical error envelope for every /v1 error response (4xx/5xx). properties: error: $ref: '#/components/schemas/ApiErrorBody' required: - error title: ApiError type: object RecommendedTutor: properties: tutor_id: type: string title: Tutor Id first_name: anyOf: - type: string - type: 'null' title: First Name last_name: anyOf: - type: string - type: 'null' title: Last Name score: type: number title: Score default: 0 breakdown: $ref: '#/components/schemas/ScoreBreakdown' reasons: items: type: string type: array title: Reasons default: [] upcoming_sessions_count: type: integer title: Upcoming Sessions Count default: 0 teaches_subject: type: boolean title: Teaches Subject default: false distance_km: anyOf: - type: number - type: 'null' title: Distance Km nearby: type: boolean title: Nearby default: false road_km: anyOf: - type: number - type: 'null' title: Road Km road_minutes: anyOf: - type: number - type: 'null' title: Road Minutes type: object required: - tutor_id - breakdown title: RecommendedTutor ApiErrorBody: description: The `error` object every /v1 error response carries. properties: code: description: >- Stable machine-readable error code: bad_request, unauthorized, forbidden, not_found, conflict, validation_error, rate_limited, or internal_error. examples: - not_found title: Code type: string message: description: Human-readable explanation, safe to surface to end users. examples: - Session not found title: Message type: string status: description: The HTTP status code, repeated in the body. examples: - 404 title: Status type: integer details: additionalProperties: true description: >- Error-specific context. 422 carries the field errors under `errors`; 429 carries `retry_after_seconds`. title: Details type: object required: - code - message - status title: ApiErrorBody type: object ScoreBreakdown: properties: subject: type: number title: Subject default: 0 availability: type: number title: Availability default: 0 mode: type: number title: Mode default: 0 capacity: type: number title: Capacity default: 0 distance: type: number title: Distance default: 0 type: object title: ScoreBreakdown description: Per-signal point contributions (sum to `score`, 0–100). securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: Org API key as `Token token=cq_live_...` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.