Skip to content

API reference

Ten paths under /v1: create a dataset, upload a version, ask what it can answer, query the grid, export the result. The response examples below are not illustrations — they are verbatim output from the engine's committed golden master, at the precision the wire actually carries.

Hand-authored

The service is live. This document is still written by hand.

The API answers at https://ptx-api.plantactic.com, and every endpoint below is reachable there today. What has not happened is the part that keeps a document honest on its own: springdoc is not wired into the service, so nothing generates this file from the code and nothing fails a build when the two disagree.

They did disagree, badly — the OAuth section described a grant type the service does not implement, the metrics endpoint documented six request fields it ignores, and the grid response promised nine fields it never sends. It was reconciled against the code on 31 August 2026. Until CI diffs generated output against it, treat the guides as authoritative where they and this disagree: they were written by running the commands.

Works on this page today

  • Browse every endpoint. Paths, parameters, status codes and schemas, against a running service.
  • Read real response examples. Grid figures are verbatim engine output from a committed golden master, not illustrations.
  • Build a request. Copy the curl, TypeScript or Python sample for any endpoint and wire it into your client.
  • Download the OpenAPI document. Generate an SDK, a Postman collection or your own mocks.

Still true, and worth knowing

  • Sending a request from this page. The API allows no browser origin on /v1, deliberately: a key callable from a web page is a leaked key. Send it from a terminal.
  • Generated from the code. springdoc is not a dependency of ptx-api, so this document is written by hand and nothing diffs it against the service.
  • api.plantactic.com. Still serves the application backend. It is not this API and pointing requests at it is an incident, not a 404.

The rule is that reference documentation is never hand-written — it is rendered from OpenAPI. This page keeps that rule and the document underneath it breaks it: the spec is hand-authored because springdoc was never added to the service. Adding it, and having CI diff its output against this file, is what retires the exception. Naming it here is the least we can do until then.

Download the OpenAPI document

Loading the contract…