Extralingo Bookings API

openapi: 3.2.0
info:
  title: Extralingo Public Bookings API
  version: 1.0.0
  summary: Search language schools, configure trips, and submit unpaid bookings.
  description: 'Version **1.0.0** of the Extralingo agent REST API. All paths below are relative to **`https://www.extralingo.com/api/v1`** (the documented base). The same routes also work under unversioned `/api/*` and remain fully supported. Breaking changes ship under `/api/v2` with at least 6 months'' notice; deprecated endpoints will eventually send `Deprecation` and `Sunset` headers before removal. **Read** endpoints need no authentication. **Write** endpoints require OAuth 2.1 (authorization code + PKCE S256; scopes `trips`, `requests`, `bookings`; discover the resource at /.well-known/oauth-protected-resource; see /auth.md). Create endpoints accept optional **`Idempotency-Key`** (IETF draft): same key + same authenticated user + same JSON body within 24 hours returns the original response; same key + different body returns **422**. When OAuth is enabled, `POST /trips` is gated like MCP `save_trip`. Finder prices are indicative; call `POST /trips/{trip_id}/price` for a live quote. create_booking is unpaid: the school still confirms, Extralingo emails the student, and payment is only via Extralingo after confirmation. Prefer POST /mcp (MCP) if you can use tools. Keep request volumes reasonable; usage may be rate-limited. Developer overview: /en/developers. Site index: /llms.txt.'
  contact:
    name: Extralingo
    url: https://www.extralingo.com/en/contact
servers:
- url: https://www.extralingo.com/api/v1
  description: Agent REST API v1 (production)
tags:
- name: Bookings
  description: Unpaid booking submit after email verification
paths:
  /bookings:
    post:
      tags:
      - Bookings
      operationId: createBooking
      summary: Submit an unpaid booking (school still confirms)
      security:
      - agentToken: []
      description: Same path as the V2 school-page Book now flow. Not confirmed. Not paid. Contact email is always the verified account email. Optional Idempotency-Key header or idempotencyKey in JSON.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trip_id:
                  type: string
                school_id:
                  type: integer
                configuration:
                  type: object
                phone:
                  type: string
                termsAccepted:
                  type: boolean
                privacyAccepted:
                  type: boolean
                idempotencyKey:
                  type: string
                  description: Optional body alias of Idempotency-Key. Same key + same payload within 24h replays the response.
                contact:
                  type: object
                  description: Optional first_name, last_name, phone. Email always comes from the verified account. A different contact.email is rejected.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Email verification required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation failed or idempotency key reused with a different payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /quotes:
    post:
      tags:
      - Bookings
      operationId: requestQuote
      summary: Request a personal quote
      security:
      - agentToken: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      description: Contact email is always the verified account email. A different contact.email is rejected.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Email verification required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation failed or idempotency key reused with a different payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: Optional. Replays the original response within 24 hours when the JSON body matches a prior request for the same user. Conflicts return 422.
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          examples:
          - false
        error:
          type: string
        code:
          type: string
        hint:
          type: string
        retryAfter:
          type: integer
          description: Seconds until the daily account-school limit resets (Europe/Amsterdam midnight).
  securitySchemes:
    agentToken:
      type: http
      scheme: bearer
      description: OAuth 2.1 access token from POST /oauth/token (authorization code + PKCE). See /auth.md.