{"openapi":"3.1.0","info":{"title":"Guardian Open Platform (BYOK) API","version":"0.1.0","description":"Guardian Open Platform (BYOK) lets an AI assistant read your own Guardian Open Platform data through the Guardian Open Platform API with a key you supply (Open Platform API key). Read-only: 6 tools (search_content, get_content_by_ids, latest_in_section, search_tags, list_sections, list_editions). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-guardian.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-guardian/docs"},"termsOfService":"https://connectorbay.com/byok-guardian/terms"},"servers":[{"url":"https://byok-guardian.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-guardian/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_content":{"post":{"operationId":"search_content","summary":"Search Guardian content by free text (AND, OR, NOT and quoted phrases) with optional section, tag and date filters. Retu","description":"Search Guardian content by free text (AND, OR, NOT and quoted phrases) with optional section, tag and date filters. Returns title, section, publication date and web link. Use for \"Find recent Guardian articles about the James Webb telescope\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Search text, for example 'james webb' or 'solar AND NOT subsidy'.","title":"Q"},"section":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this section id, for example technology or football.","title":"Section"},"tag":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only content with this tag id, for example technology/apple.","title":"Tag"},"from_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only content published on or after this date, YYYY-MM-DD.","title":"From Date"},"to_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only content published on or before this date, YYYY-MM-DD.","title":"To Date"},"order_by":{"anyOf":[{"enum":["newest","oldest","relevance"],"type":"string"},{"type":"null"}],"default":null,"description":"Order: newest, oldest or relevance (relevance is the default when q is given).","title":"Order By"},"show_fields":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Extra fields to include, comma separated: trailText, headline, byline, wordcount, thumbnail, shortUrl, standfirst, lastModified or all (all includes the full body text).","title":"Show Fields"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"search_contentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_content_by_ids":{"post":{"operationId":"get_content_by_ids","summary":"Get one or more Guardian content items by id (the path of the article URL without the domain), optionally with extra fie","description":"Get one or more Guardian content items by id (the path of the article URL without the domain), optionally with extra fields. Use for \"Get the Guardian article world/2022/oct/21/russia-ukraine-war-latest-what-we-know-on-day-240-of-the-invasion\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"ids":{"description":"Comma-separated content ids, for example 'technology/2014/feb/17/flappy-bird-clones-apple-google'.","maxLength":500,"title":"Ids","type":"string"},"show_fields":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Extra fields to include, comma separated: trailText, headline, byline, wordcount, thumbnail, shortUrl, standfirst, lastModified or all (all includes the full body text).","title":"Show Fields"}},"required":["ids"],"title":"get_content_by_idsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/latest_in_section":{"post":{"operationId":"latest_in_section","summary":"List the newest Guardian content of one section, such as world, business, science or sport. Use for \"What are the latest","description":"List the newest Guardian content of one section, such as world, business, science or sport. Use for \"What are the latest Guardian science articles\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"section":{"description":"Section id, for example science, business, world or sport.","maxLength":60,"title":"Section","type":"string"},"from_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only content published on or after this date, YYYY-MM-DD.","title":"From Date"},"show_fields":{"anyOf":[{"maxLength":120,"type":"string"},{"type":"null"}],"default":null,"description":"Extra fields to include, comma separated: trailText, headline, byline, wordcount, thumbnail, shortUrl, standfirst, lastModified or all (all includes the full body text).","title":"Show Fields"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 50).","title":"Page Size"}},"required":["section"],"title":"latest_in_sectionArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_tags":{"post":{"operationId":"search_tags","summary":"Search Guardian tags (topics, contributors, series) by exact text or title prefix, optionally by type or section. Use fo","description":"Search Guardian tags (topics, contributors, series) by exact text or title prefix, optionally by type or section. Use for \"Which Guardian tags start with 'climate'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Tags containing exactly this text.","title":"Q"},"web_title":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Tags whose title starts with this text, for example 'climat'.","title":"Web Title"},"type":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only tags of this type, for example keyword, contributor or series.","title":"Type"},"section":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only tags in this section id.","title":"Section"},"page_size":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"search_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_sections":{"post":{"operationId":"list_sections","summary":"List Guardian sections, optionally filtered by a query term, with their editions. Use for \"Which Guardian sections exist","description":"List Guardian sections, optionally filtered by a query term, with their editions. Use for \"Which Guardian sections exist about business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only sections matching this term, for example business.","title":"Q"}},"title":"list_sectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_editions":{"post":{"operationId":"list_editions","summary":"List the Guardian editions (such as UK, US, Australia, Europe and International) with their front page paths. Use for \"W","description":"List the Guardian editions (such as UK, US, Australia, Europe and International) with their front page paths. Use for \"Which Guardian editions are there\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_editionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}