HTTP API

occam-gitignore-api is a FastAPI adapter that wraps core.generate().

Run

uv run uvicorn occam_gitignore_api.app:app --host 127.0.0.1 --port 8000

OpenAPI docs are served at /docs (Swagger UI) and /redoc.

Endpoints

GET /healthz

Returns {"status": "ok"}. Used as a liveness probe.

GET /version

{
  "core_version": "0.1.3",
  "rules_table_version": "sha256:72fd0c323cc1"
}

POST /generate

Generate from an explicit feature list (or from a tree).

Request:

{
  "tree": ["pyproject.toml", "Dockerfile"],
  "include_comments": true,
  "include_provenance": false,
  "extras": ["secrets/"]
}

Response:

{
  "content": "# Generated by occam-gitignore...\n",
  "output_hash": "sha256:0bc905...",
  "rules_table_version": "sha256:72fd0c323cc1",
  "core_version": "0.1.3",
  "rules": [
    { "pattern": "__pycache__/", "source": "template", "feature": "python" }
  ]
}

Headers:

• ETag: "sha256:0bc905..." — equal to output_hash. Use it for HTTP caching: send If-None-Match and you'll get a 304 Not Modified when the inputs haven't changed.

POST /diff_against

Returns the patterns that would be added or removed versus an existing .gitignore:

{ "existing": "*.pyc\nnode_modules/\n", "tree": ["pyproject.toml"] }

{
  "added":   ["__pycache__/", ".DS_Store", "..."],
  "removed": ["*.pyc"]
}

Determinism

The API does not break the determinism contract: the response payload is a serialisation of the same GitignoreOutput returned by the CLI. The output_hash field is content-addressed and matches the ETag.