Extralingo Destinations API

openapi: 3.2.0
info:
  title: Extralingo Public Destinations 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: Destinations
  description: Search cities, countries and languages
paths:
  /header-search/destinations:
    get:
      tags:
      - Destinations
      operationId: searchDestinations
      summary: Search destinations (cities, countries) and schools by name
      description: Typo-tolerant search over the destinations index. With an empty `q` it returns a curated popular list. When `q` matches no place, a `schools` fallback is returned so school-name queries still resolve. Each hit includes the Extralingo URL.
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text place/school query.
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: Language slug (e.g. "spanish") to scope an empty-query browse.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 8
      - $ref: '#/components/parameters/Locale'
      responses:
        '200':
          description: Matching destinations and/or schools
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  language:
                    type: string
                  locale:
                    type: string
                  hits:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  countries:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  schools:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
  /header-search/bootstrap:
    get:
      tags:
      - Destinations
      operationId: getSearchBootstrap
      summary: Languages, course categories and popular destinations
      description: 'Static, locale-aware payload used to render the search bar: the list of languages (with landing-page URLs and country codes), course categories, and a curated popular-destinations list.'
      parameters:
      - $ref: '#/components/parameters/Locale'
      responses:
        '200':
          description: Bootstrap payload
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  parameters:
    Locale:
      name: Locale
      in: query
      required: false
      schema:
        type: string
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  securitySchemes:
    agentToken:
      type: http
      scheme: bearer
      description: OAuth 2.1 access token from POST /oauth/token (authorization code + PKCE). See /auth.md.