openapi: 3.0.3
info:
  title: An API of Ice And Fire
  version: '1.0'
  description: >-
    An API of Ice And Fire is the world's greatest source for quantified and
    structured data from the universe of A Song of Ice and Fire (and the HBO
    series Game of Thrones). Three hypermedia resources — Books, Characters,
    and Houses — are exposed read-only over HTTPS, free of authentication,
    with RFC 5988 Link-header pagination, conditional caching (ETag /
    Last-Modified), and version selection via custom media types.
  termsOfService: https://github.com/joakimskoog/AnApiOfIceAndFire/blob/master/LICENSE.md
  contact:
    name: Joakim Skoog (maintainer)
    url: https://github.com/joakimskoog/AnApiOfIceAndFire
  license:
    name: BSD 3-Clause-like
    url: https://github.com/joakimskoog/AnApiOfIceAndFire/blob/master/LICENSE.md
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
  - url: https://anapioficeandfire.com/api
    description: Production
tags:
  - name: Root
    description: API entry-point listing the top-level resource URLs.
  - name: Books
    description: Books in the A Song of Ice and Fire series.
  - name: Characters
    description: Characters from the A Song of Ice and Fire universe.
  - name: Houses
    description: Noble houses of Westeros and Essos.
paths:
  /:
    get:
      operationId: getRoot
      summary: An API of Ice And Fire Get API Root
      description: >-
        Returns the API entry point with absolute URLs to the three top-level
        collections (books, characters, houses). Useful for hypermedia
        discovery — clients can crawl the API from this endpoint alone.
      tags:
        - Root
      responses:
        '200':
          description: API root document.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Root'
              examples:
                GetRoot200Example:
                  summary: Default getRoot 200 response
                  x-microcks-default: true
                  value:
                    books: https://anapioficeandfire.com/api/books
                    characters: https://anapioficeandfire.com/api/characters
                    houses: https://anapioficeandfire.com/api/houses
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /books:
    get:
      operationId: listBooks
      summary: An API of Ice And Fire List Books
      description: >-
        List all books in the A Song of Ice and Fire series. Supports
        filtering by name and release-date range, plus RFC 5988 Link-header
        pagination.
      tags:
        - Books
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: name
          in: query
          description: Filter books by exact book name.
          required: false
          schema:
            type: string
        - name: fromReleaseDate
          in: query
          description: Only include books released on or after this date (ISO 8601).
          required: false
          schema:
            type: string
            format: date
        - name: toReleaseDate
          in: query
          description: Only include books released on or before this date (ISO 8601).
          required: false
          schema:
            type: string
            format: date
      responses:
        '200':
          description: A paginated list of books.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Book'
              examples:
                ListBooks200Example:
                  summary: Default listBooks 200 response
                  x-microcks-default: true
                  value:
                    - url: https://anapioficeandfire.com/api/books/1
                      name: A Game of Thrones
                      isbn: 978-0553103540
                      authors:
                        - George R. R. Martin
                      numberOfPages: 694
                      publisher: Bantam Books
                      country: United States
                      mediaType: Hardcover
                      released: '1996-08-01T00:00:00'
                      characters:
                        - https://anapioficeandfire.com/api/characters/2
                        - https://anapioficeandfire.com/api/characters/12
                        - https://anapioficeandfire.com/api/characters/13
                      povCharacters:
                        - https://anapioficeandfire.com/api/characters/148
                        - https://anapioficeandfire.com/api/characters/208
                        - https://anapioficeandfire.com/api/characters/232
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /books/{id}:
    get:
      operationId: getBook
      summary: An API of Ice And Fire Get Book by ID
      description: >-
        Retrieve a single book by its numeric ID. Returns the full hypermedia
        book resource with absolute character and POV-character URLs.
      tags:
        - Books
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The requested book.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Book'
              examples:
                GetBook200Example:
                  summary: Default getBook 200 response
                  x-microcks-default: true
                  value:
                    url: https://anapioficeandfire.com/api/books/1
                    name: A Game of Thrones
                    isbn: 978-0553103540
                    authors:
                      - George R. R. Martin
                    numberOfPages: 694
                    publisher: Bantam Books
                    country: United States
                    mediaType: Hardcover
                    released: '1996-08-01T00:00:00'
                    characters:
                      - https://anapioficeandfire.com/api/characters/2
                      - https://anapioficeandfire.com/api/characters/12
                      - https://anapioficeandfire.com/api/characters/13
                    povCharacters:
                      - https://anapioficeandfire.com/api/characters/148
                      - https://anapioficeandfire.com/api/characters/208
                      - https://anapioficeandfire.com/api/characters/232
        '304':
          $ref: '#/components/responses/NotModified'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /characters:
    get:
      operationId: listCharacters
      summary: An API of Ice And Fire List Characters
      description: >-
        List characters from the A Song of Ice and Fire universe. Supports
        filtering by name, gender, culture, birth year, death year, and
        living status, plus RFC 5988 Link-header pagination.
      tags:
        - Characters
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: name
          in: query
          description: Filter characters by name.
          required: false
          schema:
            type: string
        - name: gender
          in: query
          description: Filter characters by gender (e.g. Male, Female).
          required: false
          schema:
            type: string
        - name: culture
          in: query
          description: Filter characters by culture (e.g. Northmen, Dornish, Ironborn).
          required: false
          schema:
            type: string
        - name: born
          in: query
          description: Filter characters by birth year (free-text, e.g. "In 283 AC").
          required: false
          schema:
            type: string
        - name: died
          in: query
          description: Filter characters by death year (free-text).
          required: false
          schema:
            type: string
        - name: isAlive
          in: query
          description: Filter to only living (true) or only dead (false) characters.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A paginated list of characters.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Character'
              examples:
                ListCharacters200Example:
                  summary: Default listCharacters 200 response
                  x-microcks-default: true
                  value:
                    - url: https://anapioficeandfire.com/api/characters/583
                      name: Jon Snow
                      gender: Male
                      culture: Northmen
                      born: In 283 AC
                      died: ''
                      titles:
                        - Lord Commander of the Night's Watch
                      aliases:
                        - Lord Snow
                        - Ned Stark's Bastard
                        - The Bastard of Winterfell
                      allegiances:
                        - https://anapioficeandfire.com/api/houses/362
                      books:
                        - https://anapioficeandfire.com/api/books/5
                      povBooks:
                        - https://anapioficeandfire.com/api/books/1
                        - https://anapioficeandfire.com/api/books/2
                        - https://anapioficeandfire.com/api/books/3
                      tvSeries:
                        - Season 1
                        - Season 2
                        - Season 3
                        - Season 4
                        - Season 5
                        - Season 6
                      playedBy:
                        - Kit Harington
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /characters/{id}:
    get:
      operationId: getCharacter
      summary: An API of Ice And Fire Get Character by ID
      description: >-
        Retrieve a single character by its numeric ID. Returns the full
        hypermedia character resource with absolute allegiance, book, and
        POV-book URLs.
      tags:
        - Characters
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The requested character.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Character'
              examples:
                GetCharacter200Example:
                  summary: Default getCharacter 200 response
                  x-microcks-default: true
                  value:
                    url: https://anapioficeandfire.com/api/characters/583
                    name: Jon Snow
                    gender: Male
                    culture: Northmen
                    born: In 283 AC
                    died: ''
                    titles:
                      - Lord Commander of the Night's Watch
                    aliases:
                      - Lord Snow
                      - Ned Stark's Bastard
                      - The Bastard of Winterfell
                    allegiances:
                      - https://anapioficeandfire.com/api/houses/362
                    books:
                      - https://anapioficeandfire.com/api/books/5
                    povBooks:
                      - https://anapioficeandfire.com/api/books/1
                      - https://anapioficeandfire.com/api/books/2
                      - https://anapioficeandfire.com/api/books/3
                    tvSeries:
                      - Season 1
                      - Season 2
                      - Season 3
                      - Season 4
                      - Season 5
                      - Season 6
                    playedBy:
                      - Kit Harington
        '304':
          $ref: '#/components/responses/NotModified'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /houses:
    get:
      operationId: listHouses
      summary: An API of Ice And Fire List Houses
      description: >-
        List noble houses of Westeros and Essos. Supports filtering by name,
        region, words/motto, and various boolean has-* filters, plus RFC 5988
        Link-header pagination.
      tags:
        - Houses
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - name: name
          in: query
          description: Filter houses by exact house name.
          required: false
          schema:
            type: string
        - name: region
          in: query
          description: Filter houses by region (e.g. "The North", "The Reach").
          required: false
          schema:
            type: string
        - name: words
          in: query
          description: Filter houses by house words (motto).
          required: false
          schema:
            type: string
        - name: hasWords
          in: query
          description: Restrict to houses that have (true) or do not have (false) words.
          required: false
          schema:
            type: boolean
        - name: hasTitles
          in: query
          description: Restrict to houses that have (true) or do not have (false) titles.
          required: false
          schema:
            type: boolean
        - name: hasSeats
          in: query
          description: Restrict to houses that have (true) or do not have (false) seats.
          required: false
          schema:
            type: boolean
        - name: hasDiedOut
          in: query
          description: Restrict to extinct (true) or surviving (false) houses.
          required: false
          schema:
            type: boolean
        - name: hasAncestralWeapons
          in: query
          description: Restrict to houses that have (true) or do not have (false) ancestral weapons.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A paginated list of houses.
          headers:
            Link:
              $ref: '#/components/headers/Link'
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/House'
              examples:
                ListHouses200Example:
                  summary: Default listHouses 200 response
                  x-microcks-default: true
                  value:
                    - url: https://anapioficeandfire.com/api/houses/362
                      name: House Stark of Winterfell
                      region: The North
                      coatOfArms: A running grey direwolf, on an ice-white field
                      words: Winter is Coming
                      titles:
                        - King in the North
                        - Lord of Winterfell
                        - Warden of the North
                      seats:
                        - Winterfell
                      overlord: https://anapioficeandfire.com/api/houses/16
                      founded: Age of Heroes
                      founder: https://anapioficeandfire.com/api/characters/209
                      diedOut: ''
                      ancestralWeapons:
                        - Ice
                      cadetBranches:
                        - https://anapioficeandfire.com/api/houses/170
                        - https://anapioficeandfire.com/api/houses/215
                      swornMembers:
                        - https://anapioficeandfire.com/api/characters/2
                        - https://anapioficeandfire.com/api/characters/148
                        - https://anapioficeandfire.com/api/characters/208
        '304':
          $ref: '#/components/responses/NotModified'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /houses/{id}:
    get:
      operationId: getHouse
      summary: An API of Ice And Fire Get House by ID
      description: >-
        Retrieve a single house by its numeric ID. Returns the full
        hypermedia house resource with absolute current-lord, heir, overlord,
        founder, cadet-branch, and sworn-member URLs.
      tags:
        - Houses
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The requested house.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Last-Modified:
              $ref: '#/components/headers/LastModified'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/House'
              examples:
                GetHouse200Example:
                  summary: Default getHouse 200 response
                  x-microcks-default: true
                  value:
                    url: https://anapioficeandfire.com/api/houses/362
                    name: House Stark of Winterfell
                    region: The North
                    coatOfArms: A running grey direwolf, on an ice-white field
                    words: Winter is Coming
                    titles:
                      - King in the North
                      - Lord of Winterfell
                      - Warden of the North
                    seats:
                      - Winterfell
                    overlord: https://anapioficeandfire.com/api/houses/16
                    founded: Age of Heroes
                    founder: https://anapioficeandfire.com/api/characters/209
                    diedOut: ''
                    ancestralWeapons:
                      - Ice
                    cadetBranches:
                      - https://anapioficeandfire.com/api/houses/170
                      - https://anapioficeandfire.com/api/houses/215
                    swornMembers:
                      - https://anapioficeandfire.com/api/characters/2
                      - https://anapioficeandfire.com/api/characters/148
                      - https://anapioficeandfire.com/api/characters/208
        '304':
          $ref: '#/components/responses/NotModified'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/RateLimited'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    Id:
      name: id
      in: path
      description: Numeric resource identifier.
      required: true
      schema:
        type: integer
        format: int32
        minimum: 1
      example: 1
    Page:
      name: page
      in: query
      description: Page number (1-indexed). Defaults to 1.
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        default: 1
      example: 1
    PageSize:
      name: pageSize
      in: query
      description: Items per page (default 10, max 50).
      required: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 50
        default: 10
      example: 10
  headers:
    Link:
      description: >-
        RFC 5988 pagination links with `first`, `prev`, `next`, and `last`
        relations.
      schema:
        type: string
    ETag:
      description: Strong entity tag for conditional GETs via If-None-Match.
      schema:
        type: string
    LastModified:
      description: Last-modified timestamp for conditional GETs via If-Modified-Since.
      schema:
        type: string
    CacheControl:
      description: Cache-Control directives, typically including max-age.
      schema:
        type: string
  responses:
    NotModified:
      description: >-
        The resource has not changed since the version identified by the
        client's If-None-Match or If-Modified-Since header.
    BadRequest:
      description: Malformed request — invalid query parameter or value.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: >-
        The caller has exceeded the per-IP daily rate limit of 20,000
        requests. The window resets every 24 hours.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Root:
      type: object
      description: API root document listing top-level collection URLs.
      properties:
        books:
          type: string
          format: uri
          description: URL of the books collection.
          example: https://anapioficeandfire.com/api/books
        characters:
          type: string
          format: uri
          description: URL of the characters collection.
          example: https://anapioficeandfire.com/api/characters
        houses:
          type: string
          format: uri
          description: URL of the houses collection.
          example: https://anapioficeandfire.com/api/houses
    Book:
      type: object
      description: A book in the A Song of Ice and Fire series.
      properties:
        url:
          type: string
          format: uri
          description: Hypermedia self-link for this book.
          example: https://anapioficeandfire.com/api/books/1
        name:
          type: string
          description: Book title.
          example: A Game of Thrones
        isbn:
          type: string
          description: ISBN-10 or ISBN-13 identifier.
          example: 978-0553103540
        authors:
          type: array
          description: Author names.
          items:
            type: string
          example:
            - George R. R. Martin
        numberOfPages:
          type: integer
          format: int32
          description: Page count.
          example: 694
        publisher:
          type: string
          description: Publishing company.
          example: Bantam Books
        country:
          type: string
          description: Country of publication.
          example: United States
        mediaType:
          type: string
          description: Release format (e.g. Hardcover, Paperback).
          example: Hardcover
        released:
          type: string
          format: date-time
          description: Release date in ISO 8601 format.
          example: '1996-08-01T00:00:00'
        characters:
          type: array
          description: URLs of characters featured in the book.
          items:
            type: string
            format: uri
          example:
            - https://anapioficeandfire.com/api/characters/2
            - https://anapioficeandfire.com/api/characters/12
            - https://anapioficeandfire.com/api/characters/13
        povCharacters:
          type: array
          description: URLs of characters with POV chapters in the book.
          items:
            type: string
            format: uri
          example:
            - https://anapioficeandfire.com/api/characters/148
            - https://anapioficeandfire.com/api/characters/208
            - https://anapioficeandfire.com/api/characters/232
    Character:
      type: object
      description: A character from the A Song of Ice and Fire universe.
      properties:
        url:
          type: string
          format: uri
          description: Hypermedia self-link for this character.
          example: https://anapioficeandfire.com/api/characters/583
        name:
          type: string
          description: Character name.
          example: Jon Snow
        gender:
          type: string
          description: Character gender.
          example: Male
        culture:
          type: string
          description: Character's culture (e.g. Northmen, Dornish, Ironborn).
          example: Northmen
        born:
          type: string
          description: Free-text description of when the character was born (e.g. "In 283 AC").
          example: In 283 AC
        died:
          type: string
          description: Free-text description of when the character died, if applicable.
          example: ''
        titles:
          type: array
          description: Titles held by the character.
          items:
            type: string
          example:
            - Lord Commander of the Night's Watch
        aliases:
          type: array
          description: Aliases and nicknames.
          items:
            type: string
          example:
            - Lord Snow
            - Ned Stark's Bastard
            - The Bastard of Winterfell
        father:
          type: string
          format: uri
          description: URL of the character's father.
        mother:
          type: string
          format: uri
          description: URL of the character's mother.
        spouse:
          type: string
          format: uri
          description: URL of the character's spouse.
        allegiances:
          type: array
          description: URLs of houses the character owes allegiance to.
          items:
            type: string
            format: uri
          example:
            - https://anapioficeandfire.com/api/houses/362
        books:
          type: array
          description: URLs of books in which the character appears.
          items:
            type: string
            format: uri
          example:
            - https://anapioficeandfire.com/api/books/5
        povBooks:
          type: array
          description: URLs of books in which the character has POV chapters.
          items:
            type: string
            format: uri
          example:
            - https://anapioficeandfire.com/api/books/1
            - https://anapioficeandfire.com/api/books/2
            - https://anapioficeandfire.com/api/books/3
        tvSeries:
          type: array
          description: Game of Thrones seasons in which the character appears.
          items:
            type: string
          example:
            - Season 1
            - Season 2
            - Season 3
            - Season 4
            - Season 5
            - Season 6
        playedBy:
          type: array
          description: Actor names who portrayed the character.
          items:
            type: string
          example:
            - Kit Harington
    House:
      type: object
      description: A noble house of Westeros or Essos.
      properties:
        url:
          type: string
          format: uri
          description: Hypermedia self-link for this house.
          example: https://anapioficeandfire.com/api/houses/362
        name:
          type: string
          description: House name.
          example: House Stark of Winterfell
        region:
          type: string
          description: Geographic region.
          example: The North
        coatOfArms:
          type: string
          description: Heraldic description of the house arms.
          example: A running grey direwolf, on an ice-white field
        words:
          type: string
          description: House motto.
          example: Winter is Coming
        titles:
          type: array
          description: Titles held by the house.
          items:
            type: string
          example:
            - King in the North
            - Lord of Winterfell
            - Warden of the North
        seats:
          type: array
          description: Castles and seats held by the house.
          items:
            type: string
          example:
            - Winterfell
        currentLord:
          type: string
          format: uri
          description: URL of the current lord (character) of the house.
        heir:
          type: string
          format: uri
          description: URL of the current heir (character) of the house.
        overlord:
          type: string
          format: uri
          description: URL of the overlord (house) above this house.
          example: https://anapioficeandfire.com/api/houses/16
        founded:
          type: string
          description: Free-text year the house was founded.
          example: Age of Heroes
        founder:
          type: string
          format: uri
          description: URL of the character who founded the house.
          example: https://anapioficeandfire.com/api/characters/209
        diedOut:
          type: string
          description: Free-text year the house died out, if applicable.
          example: ''
        ancestralWeapons:
          type: array
          description: Names of ancestral weapons held by the house.
          items:
            type: string
          example:
            - Ice
        cadetBranches:
          type: array
          description: URLs of cadet branches of this house.
          items:
            type: string
            format: uri
          example:
            - https://anapioficeandfire.com/api/houses/170
            - https://anapioficeandfire.com/api/houses/215
        swornMembers:
          type: array
          description: URLs of characters sworn to this house.
          items:
            type: string
            format: uri
          example:
            - https://anapioficeandfire.com/api/characters/2
            - https://anapioficeandfire.com/api/characters/148
            - https://anapioficeandfire.com/api/characters/208
    Error:
      type: object
      description: Error response envelope.
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: The requested resource could not be found.