{
  "openapi": "3.1.0",
  "info": {
    "title": "Prisoner Legal Aid public API",
    "version": "1.0.0",
    "summary": "Read-only public data from prisonerlegalaid.com.",
    "description": "Prisoner Legal Aid LLC is a paralegal service, not a law firm. This API is public, read-only and needs no authentication. Site overview for agents: https://prisonerlegalaid.com/llms.txt",
    "contact": {
      "name": "Prisoner Legal Aid",
      "email": "info@prisonerlegalaid.com",
      "url": "https://prisonerlegalaid.com/contact/"
    }
  },
  "servers": [
    {
      "url": "https://prisonerlegalaid.com"
    }
  ],
  "security": [],
  "paths": {
    "/api/youtube-videos": {
      "get": {
        "operationId": "listVideos",
        "summary": "Latest videos from the Prisoner Legal Aid YouTube channel",
        "description": "Returns the newest videos (id and title) from our permanent video list, refreshed from YouTube's channel feed. Cached at the edge for 15 minutes.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of videos to return.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "longform",
            "in": "query",
            "required": false,
            "description": "Set to 1 to exclude YouTube Shorts.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Video list. empty is true when the channel genuinely has no videos.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "videos",
                    "channelUrl"
                  ],
                  "properties": {
                    "videos": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "YouTube video id; watch at https://www.youtube.com/watch?v={id}"
                          },
                          "title": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "channelUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "empty": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method other than GET.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "not_found"
                        },
                        "message": {
                          "type": "string"
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next."
                        },
                        "docs": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "YouTube could not be reached. videos holds the last good copy if one exists, flagged stale.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "videos": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "channelUrl": {
                      "type": "string"
                    },
                    "stale": {
                      "type": "boolean"
                    },
                    "staleSavedAt": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "example": "not_found"
                        },
                        "message": {
                          "type": "string"
                        },
                        "hint": {
                          "type": "string",
                          "description": "What to do next."
                        },
                        "docs": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "not_found"
              },
              "message": {
                "type": "string"
              },
              "hint": {
                "type": "string",
                "description": "What to do next."
              },
              "docs": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}