{
  "openapi": "3.1.0",
  "info": {
    "title": "AAOE Government Rate Feed",
    "version": "2026-08-01",
    "description": "Read-only, effective-dated government travel and expense rates with authoritative source and evidence metadata.",
    "contact": { "email": "api@aaoe.ai" },
    "license": { "name": "Source-specific terms apply" }
  },
  "servers": [{ "url": "https://aaoe.ai" }],
  "tags": [
    { "name": "Rates" },
    { "name": "Sources" },
    { "name": "Evidence" },
    { "name": "Operations" }
  ],
  "paths": {
    "/v1": {
      "get": {
        "summary": "API manifest",
        "operationId": "getManifest",
        "responses": { "200": { "description": "Service manifest", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/v1/rates": {
      "get": {
        "tags": ["Rates"],
        "summary": "List applicable rate observations",
        "operationId": "listRates",
        "parameters": [
          { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["mileage", "per_diem", "tax"] } },
          { "name": "country", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "US" } },
          { "name": "category", "in": "query", "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$" } },
          { "name": "as_of", "in": "query", "description": "Expense or travel date used for effective-date selection.", "schema": { "type": "string", "format": "date" } },
          { "name": "postal_code", "in": "query", "description": "Required for on-demand GSA per diem retrieval.", "schema": { "type": "string", "pattern": "^[0-9]{5}$" } },
          { "name": "fiscal_year", "in": "query", "description": "Federal fiscal year for GSA per diem retrieval.", "schema": { "type": "integer", "minimum": 2023, "maximum": 2028 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }
        ],
        "responses": {
          "200": { "description": "Applicable observations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateListEnvelope" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/rates/{observation_id}": {
      "get": {
        "tags": ["Rates"],
        "summary": "Get one immutable observation",
        "operationId": "getRateObservation",
        "parameters": [{ "name": "observation_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Observation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateEnvelope" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "tags": ["Sources"],
        "summary": "List authoritative sources and connector states",
        "operationId": "listSources",
        "responses": { "200": { "description": "Source registry", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/v1/sources/{source_id}": {
      "get": {
        "tags": ["Sources"],
        "summary": "Get source metadata",
        "operationId": "getSource",
        "parameters": [{ "name": "source_id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "Source record" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/v1/evidence/{sha256}": {
      "get": {
        "tags": ["Evidence"],
        "summary": "Get public evidence metadata",
        "description": "Raw evidence remains private by default and is not returned by this endpoint.",
        "operationId": "getEvidenceMetadata",
        "parameters": [{ "name": "sha256", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }],
        "responses": { "200": { "description": "Evidence metadata" }, "404": { "$ref": "#/components/responses/NotFound" } }
      }
    },
    "/health": {
      "get": {
        "tags": ["Operations"],
        "summary": "Service health",
        "operationId": "getHealth",
        "responses": { "200": { "description": "Healthy" }, "503": { "description": "Degraded" } }
      }
    }
  },
  "components": {
    "schemas": {
      "EvidenceReference": {
        "type": "object",
        "required": ["status", "canonical_url", "retention_class"],
        "properties": {
          "status": { "type": "string", "enum": ["archived", "source_linked", "pending"] },
          "artifact_sha256": { "type": ["string", "null"], "pattern": "^[a-f0-9]{64}$" },
          "canonical_url": { "type": "string", "format": "uri" },
          "retention_class": { "type": "string" }
        }
      },
      "Jurisdiction": {
        "type": "object",
        "required": ["country"],
        "properties": {
          "country": { "type": "string", "pattern": "^[A-Z]{2}$" },
          "subdivision": { "type": ["string", "null"] },
          "locality": { "type": ["string", "null"] },
          "postal_code": { "type": ["string", "null"] }
        }
      },
      "RateObservation": {
        "type": "object",
        "required": ["observation_id", "type", "category", "amount", "currency", "unit", "jurisdiction", "effective_from", "status", "source_id", "source_url", "evidence"],
        "properties": {
          "observation_id": { "type": "string" },
          "natural_key": { "type": "string" },
          "type": { "type": "string", "enum": ["mileage", "per_diem", "tax", "meal_rate", "customs_duty"] },
          "category": { "type": "string" },
          "amount": { "type": "number", "minimum": 0 },
          "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "description": "Null for dimensionless percentage rates." },
          "unit": { "type": "string" },
          "jurisdiction": { "$ref": "#/components/schemas/Jurisdiction" },
          "effective_from": { "type": "string", "format": "date" },
          "effective_to": { "type": ["string", "null"], "format": "date" },
          "published_at": { "type": ["string", "null"] },
          "observed_at": { "type": "string", "format": "date-time" },
          "status": { "type": "string", "enum": ["verified", "provisional", "withdrawn", "superseded"] },
          "source_id": { "type": "string" },
          "source_url": { "type": "string", "format": "uri" },
          "content_sha256": { "type": ["string", "null"] },
          "scope": { "type": "object", "additionalProperties": true, "description": "Source-specific qualifiers such as a VAT category or classification codes." },
          "evidence": { "$ref": "#/components/schemas/EvidenceReference" }
        }
      },
      "Meta": {
        "type": "object",
        "required": ["request_id", "retrieved_at"],
        "properties": { "request_id": { "type": "string", "format": "uuid" }, "retrieved_at": { "type": "string", "format": "date-time" } }
      },
      "RateListEnvelope": {
        "type": "object",
        "required": ["api_version", "data", "meta"],
        "properties": { "api_version": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RateObservation" } }, "meta": { "$ref": "#/components/schemas/Meta" } }
      },
      "RateEnvelope": {
        "type": "object",
        "required": ["api_version", "data", "meta"],
        "properties": { "api_version": { "type": "string" }, "data": { "$ref": "#/components/schemas/RateObservation" }, "meta": { "$ref": "#/components/schemas/Meta" } }
      },
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } } }
      }
    },
    "responses": {
      "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unavailable": { "description": "Connector or service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}