{
  "openapi": "3.0.3",
  "info": {
    "title": "The Guardian Content API",
    "description": "The Guardian's Open Platform Content API provides free access to all content published on theguardian.com. Search for articles, browse sections and tags, retrieve specific content items, and access edition-specific content. Supports filtering by date, section, tag, and more.",
    "version": "2.0.0",
    "contact": {
      "name": "The Guardian Open Platform",
      "url": "https://open-platform.theguardian.com/"
    },
    "termsOfService": "https://open-platform.theguardian.com/access/",
    "x-jentic-source-url": "https://open-platform.theguardian.com/"
  },
  "servers": [
    {
      "url": "https://content.guardianapis.com",
      "description": "Guardian Content API Production Server"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "operationId": "searchContent",
        "summary": "Search for content",
        "description": "Search all Guardian content. Returns articles, liveblogs, galleries, and other content types matching the query. Results are paginated and can be filtered by section, tag, date range, and more.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Full-text search query. Supports AND, OR, NOT operators.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query-fields",
            "in": "query",
            "description": "Specify which indexed fields are used by the q parameter (e.g., headline, body, all)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "section",
            "in": "query",
            "description": "Filter by section ID (e.g., technology, sport). Use | for OR, - prefix to exclude.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "Filter by tag ID (e.g., technology/apple). Use comma for AND, | for OR, - to exclude.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by content type",
            "schema": {
              "type": "string",
              "enum": [
                "article",
                "liveblog",
                "gallery",
                "interactive",
                "picture",
                "video",
                "crossword",
                "audio"
              ]
            }
          },
          {
            "name": "from-date",
            "in": "query",
            "description": "Return content published on or after this date (YYYY-MM-DD)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to-date",
            "in": "query",
            "description": "Return content published on or before this date (YYYY-MM-DD)",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "order-by",
            "in": "query",
            "description": "Sort order for results",
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "oldest",
                "relevance"
              ],
              "default": "relevance"
            }
          },
          {
            "name": "show-fields",
            "in": "query",
            "description": "Comma-separated list of article fields to include (e.g., body,headline,thumbnail,shortUrl,byline,trailText,wordcount,starRating,all)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-tags",
            "in": "query",
            "description": "Comma-separated list of tag types to include (e.g., keyword,contributor,series,blog,tone,type,all)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-elements",
            "in": "query",
            "description": "Include media elements (image, video, audio, all)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-blocks",
            "in": "query",
            "description": "Include block-level content (body, all, main)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-references",
            "in": "query",
            "description": "Include references",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page-size",
            "in": "query",
            "description": "Number of results per page (max 50 for free tier)",
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 200
            }
          },
          {
            "name": "use-date",
            "in": "query",
            "description": "Which date to use for filtering and ordering",
            "schema": {
              "type": "string",
              "enum": [
                "published",
                "first-publication",
                "newspaper-edition",
                "last-modified"
              ]
            }
          },
          {
            "name": "lang",
            "in": "query",
            "description": "ISO language code to filter content by language",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "star-rating",
            "in": "query",
            "description": "Filter by star rating (for reviews)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5
            }
          },
          {
            "name": "production-office",
            "in": "query",
            "description": "Filter by production office",
            "schema": {
              "type": "string",
              "enum": [
                "uk",
                "us",
                "aus"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/{contentId}": {
      "get": {
        "operationId": "getItem",
        "summary": "Get a single content item",
        "description": "Retrieve a specific content item by its ID path (e.g., technology/2024/jan/01/article-slug).",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "contentId",
            "in": "path",
            "required": true,
            "description": "The ID (path) of the content item (e.g., world/2024/jan/01/article-slug)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-fields",
            "in": "query",
            "description": "Comma-separated list of fields to include",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-tags",
            "in": "query",
            "description": "Comma-separated list of tag types to include",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-elements",
            "in": "query",
            "description": "Include media elements",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-blocks",
            "in": "query",
            "description": "Include block-level content",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "show-references",
            "in": "query",
            "description": "Include references",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with content item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemResponse"
                }
              }
            }
          },
          "404": {
            "description": "Content item not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/tags": {
      "get": {
        "operationId": "searchTags",
        "summary": "Search for tags",
        "description": "Search for tags (keywords, series, contributors, blogs, etc.). Tags are used to classify content and can be used for filtering in the search endpoint.",
        "tags": [
          "Tags"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query for tag names",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Filter by tag type",
            "schema": {
              "type": "string",
              "enum": [
                "keyword",
                "series",
                "contributor",
                "blog",
                "tone",
                "type",
                "newspaper-book",
                "newspaper-book-section",
                "tracking",
                "paid-content"
              ]
            }
          },
          {
            "name": "section",
            "in": "query",
            "description": "Filter tags by section",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "page-size",
            "in": "query",
            "description": "Results per page",
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with tags",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TagsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/sections": {
      "get": {
        "operationId": "getSections",
        "summary": "List all sections",
        "description": "Retrieve all Guardian sections. Sections represent the major content categories like News, Sport, Culture, etc.",
        "tags": [
          "Sections"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query for section names",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response with sections",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SectionsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/editions": {
      "get": {
        "operationId": "getEditions",
        "summary": "List all editions",
        "description": "Retrieve all Guardian editions (UK, US, Australia, International, Europe).",
        "tags": [
          "Editions"
        ],
        "responses": {
          "200": {
            "description": "Successful response with editions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EditionsResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "api-key",
        "description": "API key obtained from https://open-platform.theguardian.com/access/. A test key 'test' is available for development."
      }
    },
    "schemas": {
      "SearchResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "description": "Response status",
                "enum": [
                  "ok",
                  "error"
                ]
              },
              "userTier": {
                "type": "string",
                "description": "API access tier",
                "enum": [
                  "developer",
                  "partner",
                  "internal"
                ]
              },
              "total": {
                "type": "integer",
                "description": "Total number of results"
              },
              "startIndex": {
                "type": "integer",
                "description": "Starting index of results"
              },
              "pageSize": {
                "type": "integer",
                "description": "Number of results per page"
              },
              "currentPage": {
                "type": "integer",
                "description": "Current page number"
              },
              "pages": {
                "type": "integer",
                "description": "Total number of pages"
              },
              "orderBy": {
                "type": "string",
                "description": "Sort order of results"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ContentItem"
                }
              }
            }
          }
        }
      },
      "ItemResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "userTier": {
                "type": "string"
              },
              "total": {
                "type": "integer"
              },
              "content": {
                "$ref": "#/components/schemas/ContentItem"
              }
            }
          }
        }
      },
      "ContentItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique content identifier path"
          },
          "type": {
            "type": "string",
            "description": "Content type",
            "enum": [
              "article",
              "liveblog",
              "gallery",
              "interactive",
              "picture",
              "video",
              "crossword",
              "audio"
            ]
          },
          "sectionId": {
            "type": "string",
            "description": "Section identifier"
          },
          "sectionName": {
            "type": "string",
            "description": "Human-readable section name"
          },
          "webPublicationDate": {
            "type": "string",
            "format": "date-time",
            "description": "Publication date in ISO 8601 format"
          },
          "webTitle": {
            "type": "string",
            "description": "Article headline"
          },
          "webUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL on theguardian.com"
          },
          "apiUrl": {
            "type": "string",
            "format": "uri",
            "description": "API URL for this content item"
          },
          "isHosted": {
            "type": "boolean",
            "description": "Whether the content is hosted by the Guardian"
          },
          "pillarId": {
            "type": "string",
            "description": "Content pillar identifier"
          },
          "pillarName": {
            "type": "string",
            "description": "Content pillar name"
          },
          "fields": {
            "type": "object",
            "description": "Additional fields (when show-fields is specified)",
            "properties": {
              "headline": {
                "type": "string"
              },
              "body": {
                "type": "string"
              },
              "thumbnail": {
                "type": "string"
              },
              "shortUrl": {
                "type": "string"
              },
              "byline": {
                "type": "string"
              },
              "trailText": {
                "type": "string"
              },
              "wordcount": {
                "type": "string"
              },
              "starRating": {
                "type": "string"
              },
              "standfirst": {
                "type": "string"
              },
              "lastModified": {
                "type": "string"
              },
              "publication": {
                "type": "string"
              }
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tag"
            }
          }
        }
      },
      "Tag": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Tag identifier"
          },
          "type": {
            "type": "string",
            "description": "Tag type",
            "enum": [
              "keyword",
              "series",
              "contributor",
              "blog",
              "tone",
              "type",
              "newspaper-book",
              "newspaper-book-section"
            ]
          },
          "sectionId": {
            "type": "string"
          },
          "sectionName": {
            "type": "string"
          },
          "webTitle": {
            "type": "string"
          },
          "webUrl": {
            "type": "string",
            "format": "uri"
          },
          "apiUrl": {
            "type": "string",
            "format": "uri"
          },
          "keywordType": {
            "type": "string"
          }
        }
      },
      "TagsResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "userTier": {
                "type": "string"
              },
              "total": {
                "type": "integer"
              },
              "startIndex": {
                "type": "integer"
              },
              "pageSize": {
                "type": "integer"
              },
              "currentPage": {
                "type": "integer"
              },
              "pages": {
                "type": "integer"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Tag"
                }
              }
            }
          }
        }
      },
      "Section": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "webTitle": {
            "type": "string"
          },
          "webUrl": {
            "type": "string",
            "format": "uri"
          },
          "apiUrl": {
            "type": "string",
            "format": "uri"
          },
          "editions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "webTitle": {
                  "type": "string"
                },
                "webUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "apiUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "code": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "SectionsResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "userTier": {
                "type": "string"
              },
              "total": {
                "type": "integer"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Section"
                }
              }
            }
          }
        }
      },
      "Edition": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Edition identifier (uk, us, au, international, europe)"
          },
          "path": {
            "type": "string"
          },
          "edition": {
            "type": "string"
          },
          "webTitle": {
            "type": "string"
          },
          "webUrl": {
            "type": "string",
            "format": "uri"
          },
          "apiUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "EditionsResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string"
              },
              "userTier": {
                "type": "string"
              },
              "total": {
                "type": "integer"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Edition"
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "response": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "error"
                ]
              },
              "message": {
                "type": "string",
                "description": "Error message"
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKeyQuery": []
    }
  ],
  "tags": [
    {
      "name": "Content",
      "description": "Search and retrieve Guardian content items"
    },
    {
      "name": "Tags",
      "description": "Browse and search Guardian tags (keywords, series, contributors, etc.)"
    },
    {
      "name": "Sections",
      "description": "Browse Guardian sections"
    },
    {
      "name": "Editions",
      "description": "Browse Guardian editions (UK, US, AU, International, Europe)"
    }
  ]
}