SWAPI - Star Wars API People API

openapi: 3.2.0
info:
  title: SWAPI - Star Wars Films People API
  description: "SWAPI (Star Wars API) is a free, open Star Wars REST API. It exposes canonical\nStar Wars data — films, people, planets, species, starships, and vehicles — across\nthe original and prequel trilogies and the Clone Wars era. SWAPI is widely used\nas a teaching API for REST clients, framework demos, MCP server tutorials, and\nJSON parser benchmarks.\n\nTwo community mirrors are commonly used:\n  - swapi.dev   (Python/Django port maintained by @juriy)\n  - www.swapi.tech (Node/MongoDB port maintained by @semperry)\n\nThe original swapi.co project (by Paul Hallett / @phalt) is no longer maintained.\nThis OpenAPI describes the swapi.dev surface, which preserves the canonical SWAPI\nresponse shape (count / next / previous / results paginators and the flat resource\nschemas). The swapi.tech mirror wraps the same payloads inside `result.properties`.\n"
  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'
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: People
  description: Characters from the Star Wars universe (Luke Skywalker, Darth Vader, etc.).
paths:
  /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
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
          example: Not found.
    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'
    Pagination:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          description: Total number of resources in the collection.
          example: 82
        next:
          type:
          - string
          - 'null'
          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
          - 'null'
          format: uri
          description: URL of the previous page, or null if this is the first page.
          example: null
  parameters:
    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
    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
    IdParam:
      name: id
      in: path
      required: true
      description: Numeric SWAPI identifier for the resource.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
externalDocs:
  description: SWAPI Documentation (swapi.dev)
  url: https://swapi.dev/documentation