openapi: 3.0.3
info:
  title: An API of Ice and Fire books houses API
  description: An API of Ice and Fire is a free, open REST API providing comprehensive Game of Thrones and A Song of Ice and Fire data including books, characters, and houses from George R.R. Martin's universe. No authentication is required. The API offers structured, quantified data about the HBO series and book series covering all named characters, their allegiances, relationships, book appearances, TV season appearances, and details on every noble house and published book in the series.
  version: 1.0.0
  contact:
    name: Joakim Skoog
    url: https://github.com/joakimskoog
  license:
    name: MIT
    url: https://github.com/joakimskoog/AnApiOfIceAndFire/blob/master/LICENSE.md
  termsOfService: https://anapioficeandfire.com/
servers:
- url: https://www.anapioficeandfire.com/api
  description: Production server
tags:
- name: houses
  description: Noble houses from the A Song of Ice and Fire universe
paths:
  /houses:
    get:
      summary: List houses
      description: Returns a paginated list of all noble houses. Supports filtering by name, region, words, hasWords, hasTitles, hasSeats, hasDiedOut, and hasAncestralWeapons.
      operationId: listHouses
      tags:
      - houses
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - name: name
        in: query
        description: Filter houses by name.
        required: false
        schema:
          type: string
        example: House Stark
      - name: region
        in: query
        description: Filter houses by region.
        required: false
        schema:
          type: string
        example: The North
      - name: words
        in: query
        description: Filter houses by their words/motto.
        required: false
        schema:
          type: string
      - name: hasWords
        in: query
        description: Filter to houses that have words.
        required: false
        schema:
          type: boolean
      - name: hasTitles
        in: query
        description: Filter to houses that have titles.
        required: false
        schema:
          type: boolean
      - name: hasSeats
        in: query
        description: Filter to houses that have seats.
        required: false
        schema:
          type: boolean
      - name: hasDiedOut
        in: query
        description: Filter to houses that have died out.
        required: false
        schema:
          type: boolean
      - name: hasAncestralWeapons
        in: query
        description: Filter to houses that have ancestral weapons.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: A paginated list of houses.
          headers:
            Link:
              description: Hypermedia pagination links (RFC 5988).
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/House'
  /houses/{id}:
    get:
      summary: Get a house
      description: Returns a single house resource by its numeric ID.
      operationId: getHouse
      tags:
      - houses
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: A house resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/House'
        '404':
          description: House not found.
components:
  parameters:
    id:
      name: id
      in: path
      required: true
      description: Numeric identifier of the resource.
      schema:
        type: integer
        minimum: 1
      example: 1
    pageSize:
      name: pageSize
      in: query
      required: false
      description: Number of results per page (max 50).
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 10
      example: 10
    page:
      name: page
      in: query
      required: false
      description: Page number for pagination (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
  schemas:
    House:
      type: object
      description: A noble house from the A Song of Ice and Fire universe.
      properties:
        url:
          type: string
          format: uri
          description: The canonical URL of this house resource.
        name:
          type: string
          description: The full name of the house.
          example: House Stark of Winterfell
        region:
          type: string
          description: The geographic region this house is based in.
          example: The North
        coatOfArms:
          type: string
          description: Heraldic description of the house's coat of arms.
          example: A grey direwolf on a white field
        words:
          type: string
          description: The house words (motto). Empty if unknown.
          example: Winter Is Coming
        titles:
          type: array
          description: Titles held by the house.
          items:
            type: string
        seats:
          type: array
          description: Known seats (castles/strongholds) of the house.
          items:
            type: string
        currentLord:
          type: string
          format: uri
          description: URL of the current lord character. Empty string if unknown.
        heir:
          type: string
          format: uri
          description: URL of the current heir character. Empty string if unknown.
        overlord:
          type: string
          format: uri
          description: URL of the overlord house. Empty string if none.
        founded:
          type: string
          description: Text description of when the house was founded.
        founder:
          type: string
          format: uri
          description: URL of the founding character. Empty string if unknown.
        diedOut:
          type: string
          description: Text description of when the house died out. Empty if still active.
        ancestralWeapons:
          type: array
          description: Names of ancestral weapons belonging to this house.
          items:
            type: string
        cadetBranches:
          type: array
          description: URLs of cadet branch houses.
          items:
            type: string
            format: uri
        swornMembers:
          type: array
          description: URLs of characters sworn to this house.
          items:
            type: string
            format: uri
externalDocs:
  description: Official API Documentation (GitHub Wiki)
  url: https://github.com/joakimskoog/AnApiOfIceAndFire/wiki