Created
July 14, 2025 05:52
-
-
Save ryan-blunden/33209694fe772b6c485d08be58abfed5 to your computer and use it in GitHub Desktop.
StarWars OpenAPI
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
openapi: 3.1.0 | |
info: | |
title: SWAPI - The Star Wars API | |
description: | | |
SWAPI (Star Wars API) is a RESTful API that provides comprehensive data about the Star Wars universe. | |
This API includes information about films, people, planets, species, starships, and vehicles from the Star Wars saga. | |
All endpoints are read-only and return JSON data. The API is hosted on a highly available CDN network | |
for fast response times and high reliability. | |
version: 1.0.0 | |
contact: | |
name: SWAPI.INFO | |
url: https://swapi.info | |
license: | |
name: MIT | |
url: https://github.com/swapi-info/swapi-info/blob/main/LICENSE | |
servers: | |
- url: https://swapi.info/api | |
description: Production server | |
paths: | |
/: | |
get: | |
summary: Get API root | |
description: Returns the root resource with links to all available resource categories | |
operationId: getRoot | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Root' | |
example: | |
films: "https://swapi.info/api/films" | |
people: "https://swapi.info/api/people" | |
planets: "https://swapi.info/api/planets" | |
species: "https://swapi.info/api/species" | |
vehicles: "https://swapi.info/api/vehicles" | |
starships: "https://swapi.info/api/starships" | |
/films: | |
get: | |
summary: Get all films | |
description: Returns a list of all Star Wars films | |
operationId: getAllFilms | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Film' | |
/films/{id}: | |
get: | |
summary: Get a specific film | |
description: Returns a specific film by ID | |
operationId: getFilm | |
parameters: | |
- name: id | |
in: path | |
required: true | |
description: The ID of the film to retrieve | |
schema: | |
type: integer | |
minimum: 1 | |
maximum: 6 | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Film' | |
'404': | |
description: Film not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
example: | |
detail: "Not found" | |
/films/schema: | |
get: | |
summary: Get film schema | |
description: Returns the JSON schema for film resources | |
operationId: getFilmSchema | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: object | |
/people: | |
get: | |
summary: Get all people | |
description: Returns a list of all people in the Star Wars universe | |
operationId: getAllPeople | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Person' | |
/people/{id}: | |
get: | |
summary: Get a specific person | |
description: Returns a specific person by ID | |
operationId: getPerson | |
parameters: | |
- name: id | |
in: path | |
required: true | |
description: The ID of the person to retrieve | |
schema: | |
type: integer | |
minimum: 1 | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Person' | |
'404': | |
description: Person not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
example: | |
detail: "Not found" | |
/people/schema: | |
get: | |
summary: Get people schema | |
description: Returns the JSON schema for people resources | |
operationId: getPeopleSchema | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: object | |
/planets: | |
get: | |
summary: Get all planets | |
description: Returns a list of all planets in the Star Wars universe | |
operationId: getAllPlanets | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Planet' | |
/planets/{id}: | |
get: | |
summary: Get a specific planet | |
description: Returns a specific planet by ID | |
operationId: getPlanet | |
parameters: | |
- name: id | |
in: path | |
required: true | |
description: The ID of the planet to retrieve | |
schema: | |
type: integer | |
minimum: 1 | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Planet' | |
'404': | |
description: Planet not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
example: | |
detail: "Not found" | |
/planets/schema: | |
get: | |
summary: Get planets schema | |
description: Returns the JSON schema for planet resources | |
operationId: getPlanetsSchema | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: object | |
/species: | |
get: | |
summary: Get all species | |
description: Returns a list of all species in the Star Wars universe | |
operationId: getAllSpecies | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Species' | |
/species/{id}: | |
get: | |
summary: Get a specific species | |
description: Returns a specific species by ID | |
operationId: getSpecies | |
parameters: | |
- name: id | |
in: path | |
required: true | |
description: The ID of the species to retrieve | |
schema: | |
type: integer | |
minimum: 1 | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Species' | |
'404': | |
description: Species not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
example: | |
detail: "Not found" | |
/species/schema: | |
get: | |
summary: Get species schema | |
description: Returns the JSON schema for species resources | |
operationId: getSpeciesSchema | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: object | |
/starships: | |
get: | |
summary: Get all starships | |
description: Returns a list of all starships in the Star Wars universe | |
operationId: getAllStarships | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Starship' | |
/starships/{id}: | |
get: | |
summary: Get a specific starship | |
description: Returns a specific starship by ID | |
operationId: getStarship | |
parameters: | |
- name: id | |
in: path | |
required: true | |
description: The ID of the starship to retrieve | |
schema: | |
type: integer | |
minimum: 1 | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Starship' | |
'404': | |
description: Starship not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
example: | |
detail: "Not found" | |
/starships/schema: | |
get: | |
summary: Get starships schema | |
description: Returns the JSON schema for starship resources | |
operationId: getStarshipsSchema | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: object | |
/vehicles: | |
get: | |
summary: Get all vehicles | |
description: Returns a list of all vehicles in the Star Wars universe | |
operationId: getAllVehicles | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: array | |
items: | |
$ref: '#/components/schemas/Vehicle' | |
/vehicles/{id}: | |
get: | |
summary: Get a specific vehicle | |
description: Returns a specific vehicle by ID | |
operationId: getVehicle | |
parameters: | |
- name: id | |
in: path | |
required: true | |
description: The ID of the vehicle to retrieve | |
schema: | |
type: integer | |
minimum: 1 | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Vehicle' | |
'404': | |
description: Vehicle not found | |
content: | |
application/json: | |
schema: | |
$ref: '#/components/schemas/Error' | |
example: | |
detail: "Not found" | |
/vehicles/schema: | |
get: | |
summary: Get vehicles schema | |
description: Returns the JSON schema for vehicle resources | |
operationId: getVehiclesSchema | |
responses: | |
'200': | |
description: Successful response | |
content: | |
application/json: | |
schema: | |
type: object | |
components: | |
schemas: | |
Root: | |
type: object | |
description: The root resource containing links to all available resource categories | |
properties: | |
films: | |
type: string | |
format: uri | |
description: URL to the films resource | |
example: "https://swapi.info/api/films" | |
people: | |
type: string | |
format: uri | |
description: URL to the people resource | |
example: "https://swapi.info/api/people" | |
planets: | |
type: string | |
format: uri | |
description: URL to the planets resource | |
example: "https://swapi.info/api/planets" | |
species: | |
type: string | |
format: uri | |
description: URL to the species resource | |
example: "https://swapi.info/api/species" | |
vehicles: | |
type: string | |
format: uri | |
description: URL to the vehicles resource | |
example: "https://swapi.info/api/vehicles" | |
starships: | |
type: string | |
format: uri | |
description: URL to the starships resource | |
example: "https://swapi.info/api/starships" | |
required: | |
- films | |
- people | |
- planets | |
- species | |
- vehicles | |
- starships | |
Film: | |
type: object | |
description: A Star Wars film | |
properties: | |
title: | |
type: string | |
description: The title of this film | |
example: "A New Hope" | |
episode_id: | |
type: integer | |
description: The episode number of this film | |
example: 4 | |
opening_crawl: | |
type: string | |
description: The opening paragraphs at the beginning of this film | |
director: | |
type: string | |
description: The name of the director of this film | |
example: "George Lucas" | |
producer: | |
type: string | |
description: The name(s) of the producer(s) of this film | |
example: "Gary Kurtz, Rick McCallum" | |
release_date: | |
type: string | |
format: date | |
description: The ISO 8601 date format of film release at original creator country | |
example: "1977-05-25" | |
characters: | |
type: array | |
description: An array of people resource URLs that are in this film | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/people/1" | |
planets: | |
type: array | |
description: An array of planet resource URLs that are in this film | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/planets/1" | |
starships: | |
type: array | |
description: An array of starship resource URLs that are in this film | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/starships/2" | |
vehicles: | |
type: array | |
description: An array of vehicle resource URLs that are in this film | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/vehicles/4" | |
species: | |
type: array | |
description: An array of species resource URLs that are in this film | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/species/1" | |
created: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was created | |
example: "2014-12-10T14:23:31.880000Z" | |
edited: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was edited | |
example: "2014-12-20T19:49:45.256000Z" | |
url: | |
type: string | |
format: uri | |
description: The hypermedia URL of this resource | |
example: "https://swapi.info/api/films/1" | |
required: | |
- title | |
- episode_id | |
- opening_crawl | |
- director | |
- producer | |
- release_date | |
- characters | |
- planets | |
- starships | |
- vehicles | |
- species | |
- created | |
- edited | |
- url | |
Person: | |
type: object | |
description: A person within the Star Wars universe | |
properties: | |
name: | |
type: string | |
description: The name of this person | |
example: "Luke Skywalker" | |
height: | |
type: string | |
description: The height of the person in centimeters | |
example: "172" | |
mass: | |
type: string | |
description: The mass of the person in kilograms | |
example: "77" | |
hair_color: | |
type: string | |
description: The hair color of this person | |
example: "blond" | |
skin_color: | |
type: string | |
description: The skin color of this person | |
example: "fair" | |
eye_color: | |
type: string | |
description: The eye color of this person | |
example: "blue" | |
birth_year: | |
type: string | |
description: The birth year of the person, using the in-universe standard of BBY or ABY | |
example: "19BBY" | |
gender: | |
type: string | |
description: The gender of this person | |
example: "male" | |
homeworld: | |
type: string | |
format: uri | |
description: The URL of a planet resource, a planet that this person was born on or inhabits | |
example: "https://swapi.info/api/planets/1" | |
films: | |
type: array | |
description: An array of film resource URLs that this person has been in | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/films/1" | |
species: | |
type: array | |
description: An array of species resource URLs that this person belongs to | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/species/1" | |
vehicles: | |
type: array | |
description: An array of vehicle resource URLs that this person has piloted | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/vehicles/14" | |
starships: | |
type: array | |
description: An array of starship resource URLs that this person has piloted | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/starships/12" | |
created: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was created | |
example: "2014-12-09T13:50:51.644000Z" | |
edited: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was edited | |
example: "2014-12-20T21:17:56.891000Z" | |
url: | |
type: string | |
format: uri | |
description: The hypermedia URL of this resource | |
example: "https://swapi.info/api/people/1" | |
required: | |
- name | |
- height | |
- mass | |
- hair_color | |
- skin_color | |
- eye_color | |
- birth_year | |
- gender | |
- homeworld | |
- films | |
- species | |
- vehicles | |
- starships | |
- created | |
- edited | |
- url | |
Planet: | |
type: object | |
description: A large mass, planet or planetoid in the Star Wars Universe | |
properties: | |
name: | |
type: string | |
description: The name of this planet | |
example: "Tatooine" | |
rotation_period: | |
type: string | |
description: The number of standard hours it takes for this planet to complete a single rotation on its axis | |
example: "23" | |
orbital_period: | |
type: string | |
description: The number of standard days it takes for this planet to complete a single orbit of its local star | |
example: "304" | |
diameter: | |
type: string | |
description: The diameter of this planet in kilometers | |
example: "10465" | |
climate: | |
type: string | |
description: The climate of this planet | |
example: "arid" | |
gravity: | |
type: string | |
description: A number denoting the gravity of this planet, where "1" is normal or 1 standard G | |
example: "1 standard" | |
terrain: | |
type: string | |
description: The terrain of this planet | |
example: "desert" | |
surface_water: | |
type: string | |
description: The percentage of the planet surface that is naturally occurring water or bodies of water | |
example: "1" | |
population: | |
type: string | |
description: The average population of sentient beings inhabiting this planet | |
example: "200000" | |
residents: | |
type: array | |
description: An array of People URL Resources that live on this planet | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/people/1" | |
films: | |
type: array | |
description: An array of Film URL Resources that this planet has appeared in | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/films/1" | |
created: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was created | |
example: "2014-12-09T13:50:49.641000Z" | |
edited: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was edited | |
example: "2014-12-20T20:58:18.411000Z" | |
url: | |
type: string | |
format: uri | |
description: The hypermedia URL of this resource | |
example: "https://swapi.info/api/planets/1" | |
required: | |
- name | |
- rotation_period | |
- orbital_period | |
- diameter | |
- climate | |
- gravity | |
- terrain | |
- surface_water | |
- population | |
- residents | |
- films | |
- created | |
- edited | |
- url | |
Species: | |
type: object | |
description: A type of person or character within the Star Wars Universe | |
properties: | |
name: | |
type: string | |
description: The name of this species | |
example: "Human" | |
classification: | |
type: string | |
description: The classification of this species | |
example: "mammal" | |
designation: | |
type: string | |
description: The designation of this species | |
example: "sentient" | |
average_height: | |
type: string | |
description: The average height of this species in centimeters | |
example: "180" | |
skin_colors: | |
type: string | |
description: A comma-separated string of common skin colors for this species | |
example: "caucasian, black, asian, hispanic" | |
hair_colors: | |
type: string | |
description: A comma-separated string of common hair colors for this species | |
example: "blonde, brown, black, red" | |
eye_colors: | |
type: string | |
description: A comma-separated string of common eye colors for this species | |
example: "brown, blue, green, hazel, grey, amber" | |
average_lifespan: | |
type: string | |
description: The average lifespan of this species in years | |
example: "120" | |
homeworld: | |
type: string | |
format: uri | |
description: The URL of a planet resource, a planet that this species originates from | |
example: "https://swapi.info/api/planets/9" | |
language: | |
type: string | |
description: The language commonly spoken by this species | |
example: "Galactic Basic" | |
people: | |
type: array | |
description: An array of People URL Resources that are a part of this species | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/people/66" | |
films: | |
type: array | |
description: An array of Film URL Resources that this species has appeared in | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/films/1" | |
created: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was created | |
example: "2014-12-10T13:52:11.567000Z" | |
edited: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was edited | |
example: "2014-12-20T21:36:42.136000Z" | |
url: | |
type: string | |
format: uri | |
description: The hypermedia URL of this resource | |
example: "https://swapi.info/api/species/1" | |
required: | |
- name | |
- classification | |
- designation | |
- average_height | |
- skin_colors | |
- hair_colors | |
- eye_colors | |
- average_lifespan | |
- homeworld | |
- language | |
- people | |
- films | |
- created | |
- edited | |
- url | |
Starship: | |
type: object | |
description: A single transport craft that has hyperdrive capability | |
properties: | |
name: | |
type: string | |
description: The name of this starship | |
example: "Death Star" | |
model: | |
type: string | |
description: The model or official name of this starship | |
example: "DS-1 Orbital Battle Station" | |
manufacturer: | |
type: string | |
description: The manufacturer of this starship | |
example: "Imperial Department of Military Research, Sienar Fleet Systems" | |
cost_in_credits: | |
type: string | |
description: The cost of this starship new, in galactic credits | |
example: "1000000000000" | |
length: | |
type: string | |
description: The length of this starship in meters | |
example: "120000" | |
max_atmosphering_speed: | |
type: string | |
description: The maximum speed of this starship in the atmosphere | |
example: "n/a" | |
crew: | |
type: string | |
description: The number of personnel needed to run or pilot this starship | |
example: "342,953" | |
passengers: | |
type: string | |
description: The number of non-essential people this starship can transport | |
example: "843,342" | |
cargo_capacity: | |
type: string | |
description: The maximum number of kilograms that this starship can transport | |
example: "1000000000000" | |
consumables: | |
type: string | |
description: The maximum length of time that this starship can provide consumables for its entire crew without having to resupply | |
example: "3 years" | |
hyperdrive_rating: | |
type: string | |
description: The class of this starships hyperdrive | |
example: "4.0" | |
MGLT: | |
type: string | |
description: The Maximum number of Megalights this starship can travel in a standard hour | |
example: "10" | |
starship_class: | |
type: string | |
description: The class of this starship | |
example: "Deep Space Mobile Battlestation" | |
pilots: | |
type: array | |
description: An array of People URL Resources that this starship has been piloted by | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/people/1" | |
films: | |
type: array | |
description: An array of Film URL Resources that this starship has appeared in | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/films/1" | |
created: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was created | |
example: "2014-12-10T16:36:50.509000Z" | |
edited: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was edited | |
example: "2014-12-20T21:26:24.783000Z" | |
url: | |
type: string | |
format: uri | |
description: The hypermedia URL of this resource | |
example: "https://swapi.info/api/starships/9" | |
required: | |
- name | |
- model | |
- manufacturer | |
- cost_in_credits | |
- length | |
- max_atmosphering_speed | |
- crew | |
- passengers | |
- cargo_capacity | |
- consumables | |
- hyperdrive_rating | |
- MGLT | |
- starship_class | |
- pilots | |
- films | |
- created | |
- edited | |
- url | |
Vehicle: | |
type: object | |
description: A single transport craft that does not have hyperdrive capability | |
properties: | |
name: | |
type: string | |
description: The name of this vehicle | |
example: "Sand Crawler" | |
model: | |
type: string | |
description: The model or official name of this vehicle | |
example: "Digger Crawler" | |
manufacturer: | |
type: string | |
description: The manufacturer of this vehicle | |
example: "Corellia Mining Corporation" | |
cost_in_credits: | |
type: string | |
description: The cost of this vehicle new, in galactic credits | |
example: "150000" | |
length: | |
type: string | |
description: The length of this vehicle in meters | |
example: "36.8" | |
max_atmosphering_speed: | |
type: string | |
description: The maximum speed of this vehicle in the atmosphere | |
example: "30" | |
crew: | |
type: string | |
description: The number of personnel needed to run or pilot this vehicle | |
example: "46" | |
passengers: | |
type: string | |
description: The number of non-essential people this vehicle can transport | |
example: "30" | |
cargo_capacity: | |
type: string | |
description: The maximum number of kilograms that this vehicle can transport | |
example: "50000" | |
consumables: | |
type: string | |
description: The maximum length of time that this vehicle can provide consumables for its entire crew without having to resupply | |
example: "2 months" | |
vehicle_class: | |
type: string | |
description: The class of this vehicle | |
example: "wheeled" | |
pilots: | |
type: array | |
description: An array of People URL Resources that this vehicle has been piloted by | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/people/1" | |
films: | |
type: array | |
description: An array of Film URL Resources that this vehicle has appeared in | |
items: | |
type: string | |
format: uri | |
example: "https://swapi.info/api/films/1" | |
created: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was created | |
example: "2014-12-10T15:36:25.724000Z" | |
edited: | |
type: string | |
format: date-time | |
description: The ISO 8601 date format of the time that this resource was edited | |
example: "2014-12-20T21:30:21.661000Z" | |
url: | |
type: string | |
format: uri | |
description: The hypermedia URL of this resource | |
example: "https://swapi.info/api/vehicles/4" | |
required: | |
- name | |
- model | |
- manufacturer | |
- cost_in_credits | |
- length | |
- max_atmosphering_speed | |
- crew | |
- passengers | |
- cargo_capacity | |
- consumables | |
- vehicle_class | |
- pilots | |
- films | |
- created | |
- edited | |
- url | |
Error: | |
type: object | |
description: Error response | |
properties: | |
detail: | |
type: string | |
description: A human-readable explanation specific to this occurrence of the problem | |
example: "Not found" | |
required: | |
- detail |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment