openapi: 3.1.0
info:
  title: Government Impact Index (GII-US) API
  version: 0.1.0-draft
  summary: Draft contract for the GII minimum public API (methodology v1.1.1, section 10.3).
  description: >
    Pre-pilot stub. Resource semantics are normative from methodology v1.1.1;
    schemas below are illustrative and will be finalized with the pilot release.
    Every score is decomposable: score responses link to estimates, outcomes,
    sources, and the methodology version that produced them.
  contact: { name: GII-US, url: https://gii.apiautomations.com }
  license: { name: "Proprietary. All rights reserved.", url: "https://apiautomations.com/terms-conditions" }
servers:
  - url: https://gii.apiautomations.com/api/v1
    description: Live compute API (stateless; illustrative computation on supplied inputs)
  - url: https://api.gii.apiautomations.com/v1
    description: Planned production resource server (not yet live)
security:
  - bearerAuth: []

paths:
  # ---- Live compute API (implemented; runs @gii/core, @gii/lineage, @gii/codebook) ----
  /api/v1/methodology: { get: { security: [], summary: Machine-readable methodology reference: the six dimensions and the structural form of each formula. Calibration parameters are withheld., responses: { "200": { description: OK } } } }
  /api/v1/codebook: { get: { security: [], summary: Outcome codebook, parameters: [{ name: domain, in: query, required: false, schema: { type: string } }], responses: { "200": { description: OK } } } }
  /api/v1/schema/{name}: { get: { security: [], summary: Schema availability. The definitions are withheld; the response lists the record types that exist, parameters: [{ name: name, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK }, "404": { description: Unknown schema } } } }
  /api/v1/sources: { get: { security: [], summary: "Source inventory and profiles: hierarchy, retrieval preference, coverage (section 7)", parameters: [{ name: origin, in: query, required: false, schema: { type: string } }, { name: domain, in: query, required: false, schema: { type: string } }, { name: tier, in: query, required: false, schema: { type: string } }], responses: { "200": { description: OK } } } }
  /api/v1/relational: { get: { security: [], summary: "Relational table catalog: table names and the logical stores they belong to. Column definitions and the emitted DDL are withheld.", responses: { "200": { description: OK } } } }
  /api/v1/connectors: { get: { security: [], summary: "Source-connector registry - pagination, auth env-var names, endpoints (section 7.4/7.7.3); no credential values", responses: { "200": { description: OK } } } }
  /api/v1/traceability: { get: { security: [], summary: "How much of the methodology is implemented, partial, absent, or specification-only. The section-by-section matrix is withheld.", responses: { "200": { description: Traceability matrix } } } }
  /api/v1/assurance: { get: { security: [], summary: "The checks on the checks: how many metamorphic relations held, how many historical defects stay locked, how many seeded faults the catalog carries. The catalog itself is withheld, and the fault audit has no endpoint — it edits source files and re-runs whole suites.", responses: { "200": { description: Assurance report } } } }
  /api/v1/conformance: { get: { summary: "Hold the universal invariants against generated adversarial inputs. Returns counts and verdicts; the invariant statements are withheld.", parameters: [{ name: seed, in: query, required: false, schema: { type: string } }, { name: cases, in: query, required: false, schema: { type: integer } }], responses: { "200": { description: Conformance report } } } }
  /api/v1/rehearsal: { get: { summary: "Drive the synthetic pilot corpus of fictional lineages through the whole pipeline (sections 11.1-11.3)", parameters: [{ name: cases, in: query, required: false, schema: { type: integer } }, { name: at, in: query, required: false, schema: { type: string } }], responses: { "200": { description: Dress-rehearsal report } } } }
  /api/v1/intake: { get: { summary: "Run the fixture-driven multi-source intake haul from connector output to a populated Decision Event Registry (sections 7.4-8.4)", parameters: [{ name: at, in: query, required: false, schema: { type: string } }], responses: { "200": { description: Intake report } } } }
  /api/v1/downloads: { get: { security: [], summary: "Bulk data products for research reproducibility (section 10.3)", responses: { "200": { description: OK } } } }
  /api/v1/downloads/{name}: { get: { security: [], summary: "One bulk data product served as an attachment (JSON/CSV/SQL)", parameters: [{ name: name, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK }, "404": { description: Unknown product } } } }
  /api/v1/calibration: { post: { summary: "Inter-rater reliability: grade reviewer-rating matrices against the pilot thresholds (section 11.3)", requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/calibration-input.schema.json" } } } }, responses: { "200": { description: Calibration report }, "400": { description: Body is not valid JSON }, "422": { description: A rating matrix is malformed } } } }
  /api/v1/series: { post: { summary: "Assemble national/institutional/domain impact-pressure series from a frame of scored decisions (section 5.8/10.2)", requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/series-frame.schema.json" } } } }, responses: { "200": { description: Assembled series with non-duplication check }, "400": { description: Body is not valid JSON }, "422": { description: Frame could not be assembled } } } }
  /api/v1/governance: { get: { security: [], summary: "Review roles, publication eligibility, corrections policy, and the challenge process (section 9)", responses: { "200": { description: OK } } } }
  /api/v1/dossiers: { get: { summary: Index of illustrative beta decision dossiers (section 10.1/10.2), responses: { "200": { description: OK } } } }
  /api/v1/dossiers/{id}: { get: { summary: One beta decision dossier in the section 10.1 order, parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK }, "404": { description: Unknown dossier } } } }
  /api/v1/challenges: { post: { security: [], summary: Intake a structured public challenge; returns a tracking ID (section 9.6), requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/challenge-record.schema.json" } } } }, responses: { "200": { description: Challenge received with tracking ID }, "400": { description: Body is not valid JSON }, "422": { description: A required field is missing } } } }
  /api/v1/score: { post: { summary: Compute the full scorecard for a Decision Impact Record, requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/decision-impact-record.schema.json" } } } }, responses: { "200": { description: Scorecard with decomposition, withhold decision, and preregistration check }, "400": { description: Body is not valid JSON }, "422": { description: Record could not be scored } } } }
  /api/v1/sensitivity: { post: { summary: Plausible range across alternative specifications, with leave-one-out and which conclusions survive, requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/decision-impact-record.schema.json" } } } }, responses: { "200": { description: Sensitivity report }, "400": { description: Body is not valid JSON }, "422": { description: Record could not be scored } } } }
  /api/v1/release: { post: { summary: Build a reproducible, hash-timestamped release package (the server injects generatedAt), requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/decision-impact-record.schema.json" } } } }, responses: { "200": { description: Release package with manifest and verification }, "400": { description: Body is not valid JSON }, "422": { description: Package could not be built } } } }
  /api/v1/validate: { post: { summary: Quality controls plus codebook preregistration, requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/decision-impact-record.schema.json" } } } }, responses: { "200": { description: Validation report }, "400": { description: Body is not valid JSON } } } }
  /api/v1/lineage: { post: { summary: Check a Policy Lineage Graph and derive roots, leaves, and non-overlap factors, requestBody: { required: true, content: { application/json: { schema: { $ref: "https://gii.apiautomations.com/schema/policy-lineage-graph.schema.json" } } } }, responses: { "200": { description: Lineage report }, "400": { description: Body is not valid JSON } } } }
  # ---- Planned resource model (§10.3; not yet live) ----
  /decisions: { get: { summary: List Decision Impact Records, responses: { "200": { description: OK } } } }
  /decisions/{id}: { get: { summary: One Decision Impact Record, parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK } } } }
  /lineages/{id}: { get: { summary: Typed policy-lineage graph, parameters: [{ name: id, in: path, required: true, schema: { type: string } }], responses: { "200": { description: OK } } } }
  /outcomes: { get: { summary: Outcome definitions and observed series (with vintages), responses: { "200": { description: OK } } } }
  /estimates: { get: { summary: Causal estimates with design and uncertainty, responses: { "200": { description: OK } } } }
  /scores: { get: { summary: Scorecard values with evidence links, responses: { "200": { description: OK } } } }
  /series: { get: { summary: Institutional and national aggregates with coverage, responses: { "200": { description: OK } } } }
  /sources: { get: { summary: Source registry with provenance and licenses, responses: { "200": { description: OK } } } }
  /source-adapters: { get: { summary: Adapter registry, versions, and health, responses: { "200": { description: OK } } } }
  /releases: { get: { summary: Release packages and correction notices, responses: { "200": { description: OK } } } }
  /methodology: { get: { summary: Versioned methods, weights, thresholds, responses: { "200": { description: OK } } } }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        An API key issued after purchase. Send it as `Authorization: Bearer <key>`.
        The key carries its own tier and expiry and is verified locally; it is not
        stored server-side and cannot be recovered if lost. See
        https://gii.apiautomations.com/pricing
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: The same key, for clients that cannot set an Authorization header.