# U.S. Department of State

> The Department of State leads U.S. foreign policy, conducts diplomacy, issues passports and visas,
> supports U.S. citizens abroad and publishes travel advisories. It runs no unified developer portal
> and issues no API keys, but it does serve several real, anonymous, machine-readable surfaces. This
> file was generated by API Evangelist on 2026-09-07 from artifacts in the
> api-evangelist/department-of-state repository; the Department does not publish an llms.txt of its
> own (https://www.state.gov/llms.txt returns 404).

## What is actually callable

- [state.gov Content API](https://www.state.gov/wp-json/): WordPress REST API, 473 routes. Anonymous
  read access to press releases, press briefings, Department reports, biographies, bureaus, country
  pages, policy issues and official travel. No key. Base: https://www.state.gov/wp-json
- [Office of the Historian Ebook Catalog API](https://history.state.gov/api/v1/catalog): OPDS Catalog
  1.1 over Atom. Browse, search and download the Foreign Relations of the United States series. No key.
- [Travel Advisories RSS](https://travel.state.gov/_res/rss/TAsTWs.xml): RSS 2.0 feed of every
  country travel advisory and its level. The only machine-readable form of the advisories.
- [Open data catalog](https://www.state.gov/data.json): DCAT-US 3.0, 397 datasets.

## Specs and artifacts in this repository

- [OpenAPI — state.gov Content API](openapi/department-of-state-state-gov-content-openapi.yml): 65
  paths, 158 operations, 35 schemas. DERIVED, not published by the Department — a mechanical
  projection of its own route index and OPTIONS schemas. Sources kept verbatim in openapi/_original/.
- [JSON Schemas](json-schema/_index.yml): 10 provider-authored draft-04 schemas, verbatim.
- [Authentication](authentication/department-of-state-authentication.yml)
- [Conventions](conventions/department-of-state-conventions.yml): pagination, field selection,
  reversibility, and what is missing.
- [Error catalog](errors/department-of-state-problem-types.yml)
- [Data model](data-model/department-of-state-data-model.yml)
- [Lifecycle](lifecycle/department-of-state-lifecycle.yml): including three retired State APIs.
- [Conformance](conformance/department-of-state-conformance.yml)
- [Vulnerability disclosure](security/department-of-state-vulnerability-disclosure.yml)
- [Well-known probe](well-known/department-of-state-well-known.yml): nine hosts, zero documents.
- [Agent skills](skills/_index.yml)

## Endpoints an agent should know

- List press releases: GET https://www.state.gov/wp-json/wp/v2/state_press_release?per_page=10&_fields=id,date,slug,link,title
- List press briefings: GET https://www.state.gov/wp-json/wp/v2/state_briefing
- List Department reports: GET https://www.state.gov/wp-json/wp/v2/state_report
- List bureaus: GET https://www.state.gov/wp-json/wp/v2/state_bureau
- List biographies: GET https://www.state.gov/wp-json/wp/v2/state_biography
- Country landing content: GET https://www.state.gov/wp-json/wp/v2/state_country
- Cross-content search: GET https://www.state.gov/wp-json/wp/v2/search?search={term}
- Recent FRUS ebooks: GET https://history.state.gov/api/v1/catalog/recent
- Search FRUS ebooks: GET https://history.state.gov/api/v1/catalog/search?q={term}

## Rules of the road

- No API key, no registration, no plan, no quota — and no published rate limit either. robots.txt on
  www.state.gov asks for crawl-delay: 5; treat that as the floor and keep concurrency at 1.
- Use `_fields` to trim responses. An untrimmed page of state_briefing is about 760KB.
- Use `slug`, not `id`, for stable lookups. Ids are unique within a content type, not across types.
- Pagination is page/per_page. Read X-WP-Total and X-WP-TotalPages from the response headers; there
  is no next cursor in the body.
- Errors are the WordPress envelope {code, message, data.status} — NOT RFC 9457 problem+json. Match
  on `code`. A 403 with an HTML body is the edge WAF, not an application error.
- title.rendered and content.rendered are HTML with entities. Decode before display.
- Write operations exist in the contract but require a Department editorial account and are not
  available to the public.

## Hosts that will refuse you

- travel.state.gov, step.state.gov and cadatacatalog.state.gov answer non-browser clients with a
  Cloudflare 403 challenge. The travel advisory RSS feed at travel.state.gov/_res/rss/TAsTWs.xml is
  the exception and serves normally.
- https://www.state.gov/wp-json/wp/v2/users is blocked at the edge (403), so author ids cannot be
  resolved anonymously.

## Docs and policy

- [Department home](https://www.state.gov/)
- [Office of the Historian developer resources](https://history.state.gov/developer)
- [Ebook Catalog API documentation](https://history.state.gov/developer/catalog)
- [Vulnerability Disclosure Policy](https://www.state.gov/bureau-of-diplomatic-technology/vulnerability-disclosure-policy)
- [Copyright information](https://www.state.gov/copyright-information)
- [Privacy policy](https://www.state.gov/privacy-policy)
- [GitHub — U.S. Department of State](https://github.com/usstatedept)
- [GitHub — Office of the Historian](https://github.com/HistoryAtState)