Skip to content
superPDF

Versioning and changes

How the API is versioned, how it changes, and the changelog.

The API version is the version of the superpdf command that serves it, currently 0.1.0. Paths start with /v1.

Check the version

Three places give it: the first line superpdf serve prints, info.version in openapi.json, and the User-Agent of job events (superPDF/0.1.0).

Terminal
curl -s http://127.0.0.1:7341/openapi.json | jq .info
Output
{
  "title": "superPDF local API",
  "version": "0.1.0",
  "description": "The superPDF tools over HTTP, served by `superpdf serve --allow-di…"
}

How the API changes

superPDF is before 1.0, so the API can still change. These are the rules it follows:

  • Additive changes stay in /v1: new tools, new optional input fields, new fields in results and events, and new problem codes.
  • Breaking changes get a new prefix. Removing or renaming a field, a tool or a problem code, or changing what a field means, happens under /v2, not in place.
  • Every change is listed below with the version that made it, and openapi.json always describes the running version.

Write clients that last

  • Ignore fields you don’t know, in results, jobs and events.
  • Branch on code, never on title or detail.
  • Treat an unknown code by its HTTP status.
  • Generate types from openapi.json, or check it against yours in your tests.

Changelog

0.1.0

  • First release of the local API: superpdf serve, bearer tokens, Host and Origin checks, and folder scope.
  • 18 tools at POST /v1/tools/<name>, with the same schemas as the MCP server.
  • Background jobs (/v1/jobs) with progress, and job events signed in the Standard Webhooks format.
  • RFC 9457 problem details with stable codes, and an OpenAPI 3.1 description.