openapi: 3.0.3
info:
  title: SWAPI - Star Wars API
  description: |
    SWAPI (Star Wars API) is a free, open Star Wars REST API. It exposes canonical
    Star Wars data — films, people, planets, species, starships, and vehicles — across
    the original and prequel trilogies and the Clone Wars era. SWAPI is widely used
    as a teaching API for REST clients, framework demos, MCP server tutorials, and
    JSON parser benchmarks.

    Two community mirrors are commonly used:
      - swapi.dev   (Python/Django port maintained by @juriy)
      - www.swapi.tech (Node/MongoDB port maintained by @semperry)

    The original swapi.co project (by Paul Hallett / @phalt) is no longer maintained.
    This OpenAPI describes the swapi.dev surface, which preserves the canonical SWAPI
    response shape (count / next / previous / results paginators and the flat resource
    schemas). The swapi.tech mirror wraps the same payloads inside `result.properties`.
  version: '1.0'
  termsOfService: https://swapi.dev/
  contact:
    name: SWAPI Community
    url: https://github.com/Juriy/swapi
  license:
    name: BSD-3-Clause
    url: https://github.com/Juriy/swapi/blob/master/LICENSE
  x-generated-from: documentation
  x-last-validated: '2026-05-29'
externalDocs:
  description: SWAPI Documentation (swapi.dev)
  url: https://swapi.dev/documentation
servers:
  - url: https://swapi.dev/api
    description: swapi.dev — Python/Django mirror (primary)
  - url: https://www.swapi.tech/api
    description: swapi.tech — Node/MongoDB mirror (alternate)
tags:
  - name: Films
    description: The Star Wars films (theatrical episodes I-VII supported by the canonical dataset).
  - name: People
    description: Characters from the Star Wars universe (Luke Skywalker, Darth Vader, etc.).
  - name: Planets
    description: Planets featured across the Star Wars films.
  - name: Species
    description: Sentient and non-sentient species of the Star Wars universe.
  - name: Starships
    description: Hyperdrive-capable starships (X-wings, Star Destroyers, Death Stars).
  - name: Vehicles
    description: Non-hyperdrive vehicles (AT-ATs, snowspeeders, sand crawlers).
paths:
  /films/:
    get:
      tags:
        - Films
      operationId: listFilms
      summary: List All Films
      description: Returns a paginated list of all Star Wars films known to SWAPI.
      parameters:
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: A page of films.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilmList'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /films/{id}/:
    get:
      tags:
        - Films
      operationId: getFilm
      summary: Get Film By Id
      description: Returns a single film by its numeric SWAPI id.
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A single film resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Film'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /people/:
    get:
      tags:
        - People
      operationId: listPeople
      summary: List All People
      description: Returns a paginated list of characters from the Star Wars universe.
      parameters:
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: A page of people.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonList'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /people/{id}/:
    get:
      tags:
        - People
      operationId: getPerson
      summary: Get Person By Id
      description: Returns a single Star Wars character by its numeric SWAPI id.
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A single person resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /planets/:
    get:
      tags:
        - Planets
      operationId: listPlanets
      summary: List All Planets
      description: Returns a paginated list of planets featured in the Star Wars films.
      parameters:
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: A page of planets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanetList'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /planets/{id}/:
    get:
      tags:
        - Planets
      operationId: getPlanet
      summary: Get Planet By Id
      description: Returns a single planet by its numeric SWAPI id.
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A single planet resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Planet'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /species/:
    get:
      tags:
        - Species
      operationId: listSpecies
      summary: List All Species
      description: Returns a paginated list of sentient and non-sentient species of the Star Wars universe.
      parameters:
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: A page of species.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeciesList'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /species/{id}/:
    get:
      tags:
        - Species
      operationId: getSpecies
      summary: Get Species By Id
      description: Returns a single species record by its numeric SWAPI id.
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A single species resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Species'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /starships/:
    get:
      tags:
        - Starships
      operationId: listStarships
      summary: List All Starships
      description: Returns a paginated list of hyperdrive-capable starships.
      parameters:
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: A page of starships.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StarshipList'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /starships/{id}/:
    get:
      tags:
        - Starships
      operationId: getStarship
      summary: Get Starship By Id
      description: Returns a single starship by its numeric SWAPI id.
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A single starship resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Starship'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vehicles/:
    get:
      tags:
        - Vehicles
      operationId: listVehicles
      summary: List All Vehicles
      description: Returns a paginated list of non-hyperdrive vehicles.
      parameters:
        - $ref: '#/components/parameters/SearchParam'
        - $ref: '#/components/parameters/PageParam'
      responses:
        '200':
          description: A page of vehicles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleList'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /vehicles/{id}/:
    get:
      tags:
        - Vehicles
      operationId: getVehicle
      summary: Get Vehicle By Id
      description: Returns a single vehicle by its numeric SWAPI id.
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A single vehicle resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vehicle'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      description: Numeric SWAPI identifier for the resource.
      schema:
        type: integer
        minimum: 1
        example: 1
    PageParam:
      name: page
      in: query
      required: false
      description: One-based page number for paginated list responses (10 items per page).
      schema:
        type: integer
        minimum: 1
        example: 1
    SearchParam:
      name: search
      in: query
      required: false
      description: Case-insensitive partial match against the resource's main name/title field.
      schema:
        type: string
        example: luke
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
          example: Not found.
    Pagination:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          description: Total number of resources in the collection.
          example: 82
        next:
          type: string
          nullable: true
          format: uri
          description: URL of the next page, or null if this is the last page.
          example: https://swapi.dev/api/people/?page=2
        previous:
          type: string
          nullable: true
          format: uri
          description: URL of the previous page, or null if this is the first page.
          example: null
    Film:
      type: object
      description: A canonical Star Wars film.
      required:
        - title
        - episode_id
        - url
      properties:
        title:
          type: string
          description: Title of the film.
          example: A New Hope
        episode_id:
          type: integer
          description: Episode number.
          example: 4
        opening_crawl:
          type: string
          description: Opening crawl text shown at the start of the film.
        director:
          type: string
          description: Name of the film's director.
          example: George Lucas
        producer:
          type: string
          description: Comma-separated list of producer names.
          example: Gary Kurtz, Rick McCallum
        release_date:
          type: string
          format: date
          description: Theatrical release date.
          example: '1977-05-25'
        characters:
          type: array
          description: URLs of characters appearing in this film.
          items:
            type: string
            format: uri
        planets:
          type: array
          description: URLs of planets featured in this film.
          items:
            type: string
            format: uri
        starships:
          type: array
          description: URLs of starships appearing in this film.
          items:
            type: string
            format: uri
        vehicles:
          type: array
          description: URLs of vehicles appearing in this film.
          items:
            type: string
            format: uri
        species:
          type: array
          description: URLs of species appearing in this film.
          items:
            type: string
            format: uri
        created:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this resource was created in the SWAPI database.
        edited:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when this resource was last edited.
        url:
          type: string
          format: uri
          description: Canonical URL of this resource.
    FilmList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Film'
    Person:
      type: object
      description: A character from the Star Wars universe.
      required:
        - name
        - url
      properties:
        name:
          type: string
          description: Name of this character.
          example: Luke Skywalker
        height:
          type: string
          description: Height in centimeters.
          example: '172'
        mass:
          type: string
          description: Mass in kilograms.
          example: '77'
        hair_color:
          type: string
          example: blond
        skin_color:
          type: string
          example: fair
        eye_color:
          type: string
          example: blue
        birth_year:
          type: string
          description: Birth year in the in-universe BBY/ABY system (Before/After Battle of Yavin).
          example: 19BBY
        gender:
          type: string
          example: male
        homeworld:
          type: string
          format: uri
          description: URL of the planet this character originates from.
        films:
          type: array
          items:
            type: string
            format: uri
        species:
          type: array
          items:
            type: string
            format: uri
        vehicles:
          type: array
          items:
            type: string
            format: uri
        starships:
          type: array
          items:
            type: string
            format: uri
        created:
          type: string
          format: date-time
        edited:
          type: string
          format: date-time
        url:
          type: string
          format: uri
    PersonList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Person'
    Planet:
      type: object
      description: A planet within the Star Wars universe.
      required:
        - name
        - url
      properties:
        name:
          type: string
          example: Tatooine
        rotation_period:
          type: string
          description: Number of standard hours it takes for the planet to complete a single rotation on its axis.
          example: '23'
        orbital_period:
          type: string
          description: Number of standard days it takes to orbit its star.
          example: '304'
        diameter:
          type: string
          description: Diameter of the planet in kilometers.
          example: '10465'
        climate:
          type: string
          example: arid
        gravity:
          type: string
          example: 1 standard
        terrain:
          type: string
          example: desert
        surface_water:
          type: string
          description: Percentage of the planet surface that is naturally occurring water or bodies of water.
          example: '1'
        population:
          type: string
          example: '200000'
        residents:
          type: array
          items:
            type: string
            format: uri
        films:
          type: array
          items:
            type: string
            format: uri
        created:
          type: string
          format: date-time
        edited:
          type: string
          format: date-time
        url:
          type: string
          format: uri
    PlanetList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Planet'
    Species:
      type: object
      description: A species in the Star Wars universe.
      required:
        - name
        - url
      properties:
        name:
          type: string
          example: Human
        classification:
          type: string
          example: mammal
        designation:
          type: string
          example: sentient
        average_height:
          type: string
          example: '180'
        skin_colors:
          type: string
        hair_colors:
          type: string
        eye_colors:
          type: string
        average_lifespan:
          type: string
          example: '120'
        homeworld:
          type: string
          format: uri
          nullable: true
        language:
          type: string
          example: Galactic Basic
        people:
          type: array
          items:
            type: string
            format: uri
        films:
          type: array
          items:
            type: string
            format: uri
        created:
          type: string
          format: date-time
        edited:
          type: string
          format: date-time
        url:
          type: string
          format: uri
    SpeciesList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Species'
    Starship:
      type: object
      description: A hyperdrive-capable starship.
      required:
        - name
        - url
      properties:
        name:
          type: string
          example: Death Star
        model:
          type: string
          example: DS-1 Orbital Battle Station
        manufacturer:
          type: string
        cost_in_credits:
          type: string
        length:
          type: string
          description: Length of the starship in meters.
        max_atmosphering_speed:
          type: string
        crew:
          type: string
        passengers:
          type: string
        cargo_capacity:
          type: string
          description: Maximum cargo this starship can transport in kilograms.
        consumables:
          type: string
          description: Maximum length of time the starship can provide consumables for its entire crew without resupply.
        hyperdrive_rating:
          type: string
        MGLT:
          type: string
          description: Maximum number of Megalights this starship can travel in a standard hour.
        starship_class:
          type: string
          example: Deep Space Mobile Battlestation
        pilots:
          type: array
          items:
            type: string
            format: uri
        films:
          type: array
          items:
            type: string
            format: uri
        created:
          type: string
          format: date-time
        edited:
          type: string
          format: date-time
        url:
          type: string
          format: uri
    StarshipList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Starship'
    Vehicle:
      type: object
      description: A non-hyperdrive vehicle.
      required:
        - name
        - url
      properties:
        name:
          type: string
          example: Snowspeeder
        model:
          type: string
        manufacturer:
          type: string
        cost_in_credits:
          type: string
        length:
          type: string
        max_atmosphering_speed:
          type: string
        crew:
          type: string
        passengers:
          type: string
        cargo_capacity:
          type: string
        consumables:
          type: string
        vehicle_class:
          type: string
          example: airspeeder
        pilots:
          type: array
          items:
            type: string
            format: uri
        films:
          type: array
          items:
            type: string
            format: uri
        created:
          type: string
          format: date-time
        edited:
          type: string
          format: date-time
        url:
          type: string
          format: uri
    VehicleList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Vehicle'