Star Wars Databank API

Complete database of characters, creatures, droids and other elements from the Star Wars universe

Checking API Status... Connecting to server

API Endpoints

GETGet category items

Returns items from the specified category with pagination support. 

GET /api/v1/:category?page=1&limit=10&search=keyword

Parameters:

  • category: Category name (characters, creatures, droids, locations, organizations, species, vehicles)
  • page: Page number (default: 1)
  • limit: Items per page (default: 10)
  • search: Search by name (optional)

GETGet single item

Returns information about a specific item.

GET /api/v1/:category/:id

Parameters:

  • category: Category name
  • id: Item ID or slug (based on name)

GETGet image

Returns an image from the specified category by filename.

GET /image/:category/:filename

Parameters:

  • category: Image category (characters, creatures, droids, etc.)
  • filename: Image filename (e.g., luke-skywalker.webp or hash like 23d30f0abe.webp)

Note: WebP format is recommended for better performance. Also supports paths with /images/ prefix: /images/:category/:filename

Usage Examples

HTTP Requests

Get first 5 characters with "droid" search

GET https://star-wars-api-v3.netlify.app/api/v1/characters?page=1&limit=5&search=droid

Get all occurrences with the phrase "sky" in the name

GET https://star-wars-api-v3.netlify.app/api/v1/characters?limit=5&search=sky

Get character image

GET https://star-wars-api-v3.netlify.app/image/characters/eb82421a2b.webp
GET https://star-wars-api-v3.netlify.app/images/characters/eb82421a2b.webp

Both variants are supported and return the same result. WebP format (.webp) is recommended for better performance and quality.

cURL Examples

Get characters with pagination and search

curl -X GET "https://star-wars-api-v3.netlify.app/api/v1/characters?page=1&limit=5&search=droid" -H "Accept: application/json"

Download image

curl -X GET "https://star-wars-api-v3.netlify.app/image/characters/bf5e8b0341.webp" --output luke-skywalker.webp

Pagination Guide

How Pagination Works

The API uses offset-based pagination to handle large datasets efficiently. Each request returns a limited number of items with metadata about the total results.

Query Parameters

  • page: Current page number (starts from 1)
  • limit: Number of items per page (max: 100, default: 10)

Navigation

Use the info object in responses to navigate through pages:

  • total: Total number of items available
  • next: URL for next page (null if last page)
  • prev: URL for previous page (null if first page)

Pagination Examples

Navigate through character pages

# First page (10 items)
GET /api/v1/characters?page=1&limit=10

# Second page (10 items)
GET /api/v1/characters?page=2&limit=10

# Get 50 items per page
GET /api/v1/characters?page=1&limit=50

# Last page calculation
# If total=964 and limit=10, last page = ceil(964/10) = 97

Combine with search

# Search with pagination
GET /api/v1/characters?search=luke&page=1&limit=5

Response Structure with Pagination

{
  "data": [
    // ... array of items
  ],
  "info": {
    "total": 964,           // Total items in database
    "page": 2,              // Current page number
    "limit": 10,            // Items per page
    "next": "/api/v1/characters?page=3&limit=10", // Next page URL
    "prev": "/api/v1/characters?page=1&limit=10"  // Previous page URL
  }
}

Best Practices

  • Start small: Use limit=10-20 for initial requests
  • Cache results: Store responses to reduce API calls
  • Check totals: Use total to calculate max pages
  • Handle edge cases: Check for null next/prev
  • Limit boundaries: Maximum limit is 100 items per page

Error Handling

  • Invalid page: Page numbers start from 1
  • Exceeded limit: Maximum 100 items per page
  • Out of range: Returns empty array if page exceeds total

Error response example

# Request: page=0 or page=-1
{
  "error": "Invalid page number. Page must be >= 1",
  "code": 400
}

Response Formats

Category List

{
  "count": 7,
  "results": [
    { "name": "characters", "count": 964, "url": "/api/v1/characters" },
    { "name": "creatures", "count": 75, "url": "/api/v1/creatures" },
    { "name": "droids", "count": 60, "url": "/api/v1/droids" },
    { "name": "locations", "count": 326, "url": "/api/v1/locations" },
    { "name": "organizations", "count": 135, "url": "/api/v1/organizations" },
    { "name": "species", "count": 82, "url": "/api/v1/species" },
    { "name": "vehicles", "count": 267, "url": "/api/v1/vehicles" }
  ],
  "fetchDate": "2025-06-27T10:00:00.000Z",
  "source": "Star Wars Databank"
}

Category Items List

{
  "data": [
    {
      "id": "64292927021f17e13fbc1e46",
      "name": "\"Hyper\" Rod",
      "image": "characters/eb82421a2b.webp",
      "description": "Jedi Knight and hero of the Rebellion"
    },
    {
      "id": "64292927021f17e13fbc1e47",
      "name": "\"Snap\" Wexley",
      "image": "characters/008bf65f0c.webp",
      "description": "Resistance pilot"
    }
  ],
  "info": {
    "total": 964,
    "page": 1,
    "limit": 2,
    "next": "/api/v1/characters?page=2&limit=2",
    "prev": null
  }
}

Single Item

{
  "id": "64292927021f17e13fbc1e46",
  "name": "\"Hyper\" Rod",
  "image": "characters/eb82421a2b.webp",
  "description": "In his specially-modified Seven Deuce Blaster, riot racer \"Hyper\" Rod is a reprogrammed protocol droid who now focuses on the uncivilized task of eliminating his opponents at the Safa Toma Speedway."
}

Database Statistics

964 Characters
75 Creatures
60 Droids
326 Locations
135 Organizations
82 Species
267 Vehicles

Last updated: June 27, 2025

API Status Monitor

Current Status

The API status is automatically checked every 10 minutes.

Status Information

  • 🟢 Online: API is fully operational
  • 🟡 Warning: API accessible but with issues
  • 🔴 Offline: API is currently unavailable
  • 🔵 Checking: Status verification in progress

Status is cached locally and updated automatically.