Proposal to design and follow OpenAPI contract

[chetanr25]

FireForm API Contract - First Draft Open for Review

Interactive docs (Swagger UI): https://fireform-gsoc.chetanr25.in

---

Why an API contract first?

Before writing a single line of backend code, I wanted to discuss about what the system accepts, returns, and promises not as a vague spec doc, but as a machine-readable OpenAPI contract that both humans and tools can work from.

The contract-first approach matters here because FireForm's pipeline has several moving parts (voice/text input → async LLM extraction → PDF generation), and without a shared contract, the API layer and the extraction logic would need to be built in lockstep by the same person. With a published contract, frontend, backend, and tests can be developed in parallel. Anyone picking up the project knows exactly what each endpoint expects without having to read the implementation.

---

How the pipeline maps to routes

The contract is organized as four sequential layers, each with its own endpoint group:

Layer	Routes	What it does
1. Input	POST /api/v1/input/text · POST /api/v1/input/voice	Accept a responder's incident narrative (text or audio)
2. AI Extraction	POST /api/v1/extract/{input_id} · GET /api/v1/extract/{extract_id}/validate	Run local LLM, extract structured data into the incident contract JSON
3. Form Generation	POST /api/v1/forms/generate/all · GET /api/v1/forms/{form_id}/pdf	Map incident data → agency-specific PDFs
4. Incident Management	GET /api/v1/incidents · GET /api/v1/incidents/{incident_id}	Tie all the pieces (input → extraction → forms) into one incident record

LLM extraction is async — the /extract call returns a job_id immediately, and the client polls /api/v1/jobs/{job_id} for status. This keeps the API responsive even when the local model takes a few seconds.

---

Template registry - extensibility without code changes

One of the core goals is that any agency should be able to register their PDF form and have it supported immediately, without a developer writing a mapper or pushing a release.

The /api/v1/templates group covers this: an agency admin uploads their PDF template, marks field positions, and maps those fields to the canonical incident contract. From that point on, POST /api/v1/forms/generate/all automatically includes their form in the output.

---

A note on multi-agency access

Right now the design targets fully local deployments one org, one server, all data stays inside their infrastructure. Agency scoping (ApiKeyAuth per agency) is already in the contract to ensure incident data is never exposed across org boundaries within a single deployment.

There's an open question worth discussing:

• should the contract also support a future shared-server model where multiple agencies connect to one hosted endpoint? That changes how auth, data isolation, and routing work. I haven't locked this in

happy to hear thoughts before it gets baked into the implementation.

---

Contract and Visual flow-chart of the functionality

This is API design which I would like to propose. (Clicking on the image below will download a PDF of 6 pages).
These APIs were designed after taking all our requirements and constraints into consideration.

---

What I'd love feedback on

• Does the four-layer pipeline structure make sense, or should extraction and form generation be collapsed?
• Any fields missing from the incident contract schema? See the incident contract schema at fireform-gsoc.chetanr25.in/incident-contract on the Swagger site.
• Thoughts on the multi-agency / shared-server question above.

The contract is the easiest thing to change right now much easier than refactoring a running backend or whole system later.

Once the API-Contract is finalised, I think we can have the contract in our codebase itself for future references.
https://fireform-gsoc.chetanr25.in

[chetanr25]

would love to hear feedback from the community
@marcvergees @vharkins1 @abhishek-8081

I believe that we need to finalise our APIs which we would be building and then work on them one by one.