{
  "openapi": "3.1.0",
  "info": {
    "title": "AlanPartridgeScripts.co.uk API",
    "version": "1.0.0",
    "summary": "Full transcripts of I'm Alan Partridge as structured JSON.",
    "description": "A free, public, read-only API. No authentication, no rate limits, CORS open to any origin.\n\nThe corpus is about 47,000 words in total and roughly 5,000 per episode, so it is meant to be\nfetched directly rather than searched. Request the episodes you want and read them in full.\n\nEvery path is also served without the `.json` extension.",
    "license": {
      "name": "Transcripts remain the property of their respective copyright holders",
      "url": "https://alanpartridgescripts.co.uk/developers"
    }
  },
  "servers": [
    {
      "url": "https://alanpartridgescripts.co.uk"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/index.json": {
      "get": {
        "operationId": "getRoot",
        "summary": "Discovery document listing every endpoint",
        "tags": [
          "Discovery"
        ],
        "responses": {
          "200": {
            "description": "API metadata and endpoint index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/programmes.json": {
      "get": {
        "operationId": "listProgrammes",
        "summary": "List all programmes",
        "tags": [
          "Programmes"
        ],
        "responses": {
          "200": {
            "description": "Every programme",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Programme"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/programmes/{programme}.json": {
      "get": {
        "operationId": "getProgramme",
        "summary": "A single programme, with its series and their episodes",
        "tags": [
          "Programmes"
        ],
        "parameters": [
          {
            "name": "programme",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "im-alan-partridge"
              ]
            },
            "example": "im-alan-partridge"
          }
        ],
        "responses": {
          "200": {
            "description": "One programme",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/ProgrammeWithSeries"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/series.json": {
      "get": {
        "operationId": "listSeries",
        "summary": "List every series across all programmes",
        "tags": [
          "Series"
        ],
        "responses": {
          "200": {
            "description": "Every series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Series"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/series/{programme}/{series}.json": {
      "get": {
        "operationId": "getSeries",
        "summary": "A single series, with its episodes",
        "tags": [
          "Series"
        ],
        "parameters": [
          {
            "name": "programme",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "im-alan-partridge"
              ]
            },
            "example": "im-alan-partridge"
          },
          {
            "name": "series",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "series-1",
                "series-2"
              ]
            },
            "example": "series-1"
          }
        ],
        "responses": {
          "200": {
            "description": "One series",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/SeriesWithEpisodes"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/episodes.json": {
      "get": {
        "operationId": "listEpisodes",
        "summary": "List every episode, without transcripts",
        "tags": [
          "Episodes"
        ],
        "responses": {
          "200": {
            "description": "Every episode",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Episode"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/episodes/{programme}/{series}/{episode}.json": {
      "get": {
        "operationId": "getEpisode",
        "summary": "A single episode with its full transcript",
        "tags": [
          "Episodes"
        ],
        "parameters": [
          {
            "name": "programme",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "im-alan-partridge"
              ]
            },
            "example": "im-alan-partridge"
          },
          {
            "name": "series",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "series-1",
                "series-2"
              ]
            },
            "example": "series-1"
          },
          {
            "name": "episode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "episode-1-a-room-with-an-alan",
                "episode-2-alan-attraction",
                "episode-3-watership-alan",
                "episode-4-basic-alan",
                "episode-5-to-kill-a-mocking-alan",
                "episode-6-towering-alan",
                "episode-1-the-talented-mr-alan",
                "episode-2-the-colour-of-alan",
                "episode-3-brave-alan",
                "episode-4-never-say-alan-again",
                "episode-5-i-know-what-alan-did-last-summer",
                "episode-6-alan-wide-shut"
              ]
            },
            "example": "episode-1-a-room-with-an-alan"
          }
        ],
        "responses": {
          "200": {
            "description": "One episode, including scenes and lines",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/EpisodeWithScenes"
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/characters.json": {
      "get": {
        "operationId": "listCharacters",
        "summary": "List every character appearing in the transcripts",
        "tags": [
          "Characters"
        ],
        "responses": {
          "200": {
            "description": "Every character",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Character"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "No such resource",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "endpoints": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "message"
        ]
      },
      "Character": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "full_name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "first_name",
          "last_name",
          "full_name"
        ]
      },
      "Line": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "line_number": {
            "type": "integer"
          },
          "character": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Character"
              },
              {
                "type": "null"
              }
            ],
            "description": "Null for stage directions, which have no speaker."
          },
          "custom_character_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "A qualifier on the speaker, e.g. \"on the phone\"."
          },
          "text": {
            "type": "string",
            "description": "The line as authored, in markdown. `_italics_` mark stage directions."
          },
          "dialogue": {
            "type": "string",
            "description": "The same line as plain text."
          }
        },
        "required": [
          "id",
          "line_number",
          "character",
          "custom_character_name",
          "text",
          "dialogue"
        ]
      },
      "Scene": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "order_in_episode": {
            "type": "integer"
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Line"
            }
          }
        },
        "required": [
          "id",
          "title",
          "order_in_episode",
          "image_url",
          "lines"
        ]
      },
      "ProgrammeReference": {
        "type": "object",
        "description": "A programme without its series, so responses do not nest indefinitely.",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "links": {
            "type": "object",
            "properties": {
              "self": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "self"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "slug",
          "links"
        ]
      },
      "SeriesReference": {
        "type": "object",
        "description": "A series without its episodes, so responses do not nest indefinitely.",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "series_number": {
            "type": "integer"
          },
          "series_code": {
            "type": "string",
            "examples": [
              "S01"
            ]
          },
          "programme": {
            "$ref": "#/components/schemas/ProgrammeReference"
          },
          "links": {
            "type": "object",
            "properties": {
              "self": {
                "type": "string",
                "format": "uri"
              },
              "web": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "self",
              "web"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "slug",
          "series_number",
          "series_code",
          "programme",
          "links"
        ]
      },
      "Episode": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "episode_number": {
            "type": "integer"
          },
          "episode_code": {
            "type": "string",
            "examples": [
              "S01E01"
            ]
          },
          "overview": {
            "type": "string",
            "description": "A one-line summary."
          },
          "description": {
            "type": "string",
            "description": "A fuller synopsis."
          },
          "first_aired": {
            "type": "string",
            "format": "date-time"
          },
          "intro_image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "series": {
            "$ref": "#/components/schemas/SeriesReference"
          },
          "links": {
            "type": "object",
            "properties": {
              "self": {
                "type": "string",
                "format": "uri"
              },
              "web": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "self",
              "web"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "slug",
          "episode_number",
          "episode_code",
          "overview",
          "description",
          "first_aired",
          "intro_image_url",
          "series",
          "links"
        ]
      },
      "EpisodeWithScenes": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Episode"
          },
          {
            "type": "object",
            "properties": {
              "scenes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Scene"
                }
              }
            },
            "required": [
              "scenes"
            ]
          }
        ]
      },
      "Series": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "series_number": {
            "type": "integer"
          },
          "series_code": {
            "type": "string",
            "examples": [
              "S01"
            ]
          },
          "overview": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "release_year": {
            "type": "integer"
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "programme": {
            "$ref": "#/components/schemas/ProgrammeReference"
          },
          "links": {
            "type": "object",
            "properties": {
              "self": {
                "type": "string",
                "format": "uri"
              },
              "web": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "self",
              "web"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "slug",
          "series_number",
          "series_code",
          "overview",
          "description",
          "release_year",
          "image_url",
          "programme",
          "links"
        ]
      },
      "SeriesWithEpisodes": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Series"
          },
          {
            "type": "object",
            "properties": {
              "episodes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Episode"
                }
              }
            },
            "required": [
              "episodes"
            ]
          }
        ]
      },
      "Programme": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "links": {
            "type": "object",
            "properties": {
              "self": {
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "self"
            ]
          }
        },
        "required": [
          "id",
          "title",
          "slug",
          "links"
        ]
      },
      "ProgrammeWithSeries": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Programme"
          },
          {
            "type": "object",
            "properties": {
              "series": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/SeriesWithEpisodes"
                }
              }
            },
            "required": [
              "series"
            ]
          }
        ]
      }
    }
  }
}