{
  "openapi": "3.0.3",
  "info": {
    "title": "Milo FedSpend API",
    "version": "0.1.0",
    "description": "Normalised JSON wrapper over USAspending.gov contract awards and Federal Register rules/notices. No API key, no KYC, no business account, no contract. Real US federal open data through one auth shape and one JSON envelope. Per-call marketplace pricing via RapidAPI.",
    "contact": {
      "name": "Milo Antaeus",
      "email": "miloantaeus@gmail.com"
    },
    "license": {
      "name": "Commercial (marketplace billing)",
      "url": "https://rapidapi.com/miloantaeus"
    }
  },
  "servers": [
    {
      "url": "https://milo-fed-spend-api.vercel.app",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000",
      "description": "Vercel dev local"
    }
  ],
  "paths": {
    "/api/healthz": {
      "get": {
        "summary": "Liveness + upstream reachability (no auth)",
        "security": [],
        "responses": {
          "200": {
            "description": "API live + upstream status"
          }
        }
      }
    },
    "/api/version": {
      "get": {
        "summary": "Build info (no auth)",
        "security": [],
        "responses": {
          "200": {
            "description": "Version"
          }
        }
      }
    },
    "/api/openapi.json": {
      "get": {
        "summary": "This OpenAPI document (no auth)",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.0.3"
          }
        }
      }
    },
    "/api/postman-collection.json": {
      "get": {
        "summary": "Postman collection (no auth)",
        "security": [],
        "responses": {
          "200": {
            "description": "Postman v2.1 collection"
          }
        }
      }
    },
    "/api/v1/awards/search": {
      "post": {
        "summary": "Search contract awards by keyword/agency/fiscal-year",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AwardsSearchRequest"
              },
              "example": {
                "keyword": "cybersecurity",
                "fiscal_year": 2025,
                "limit": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Awards (real USAspending.gov data)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AwardsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "502": {
            "description": "USAspending.gov upstream error"
          }
        }
      }
    },
    "/api/v1/awards/recent": {
      "get": {
        "summary": "Most recent contract awards by Period-of-Performance start date",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recent awards (real USAspending.gov data)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AwardsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/v1/agency/{id}": {
      "get": {
        "summary": "Single US federal agency by USAspending agency id",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,6}$"
            },
            "example": "456"
          }
        ],
        "responses": {
          "200": {
            "description": "Agency",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgencyResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad id"
          },
          "404": {
            "description": "Agency not found"
          }
        }
      }
    },
    "/api/v1/agencies/top": {
      "get": {
        "summary": "Top US agencies by spending (default FY 2025)",
        "parameters": [
          {
            "in": "query",
            "name": "fy",
            "schema": {
              "type": "string",
              "default": "2025"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Top agencies (real USAspending.gov data)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgenciesTopResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/v1/recipients/search": {
      "post": {
        "summary": "Search award recipients (contractors/grantees) by keyword",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecipientsSearchRequest"
              },
              "example": {
                "keyword": "boeing",
                "limit": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Matching awards",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AwardsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing keyword"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    },
    "/api/v1/federal-register/search": {
      "get": {
        "summary": "Search Federal Register proposed/final rules + notices",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cybersecurity"
          },
          {
            "in": "query",
            "name": "per_page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Documents",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FedRegResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing q"
          },
          "401": {
            "description": "Unauthorized"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "query",
        "name": "key"
      },
      "Bearer": {
        "type": "http",
        "scheme": "bearer"
      },
      "RapidAPIProxy": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Proxy-Secret"
      }
    },
    "schemas": {
      "AwardsSearchRequest": {
        "type": "object",
        "properties": {
          "keyword": {
            "type": "string",
            "description": "Free-text keyword"
          },
          "keywords": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "USAspending keyword array (more precise)"
          },
          "agencies": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "[{type:\"awarding\",name:\"Department of Defense\"}]"
          },
          "fiscal_year": {
            "type": "integer",
            "description": "e.g. 2025"
          },
          "fiscal_year_range": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "award_type_codes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "A",
                "B",
                "C",
                "D"
              ]
            },
            "description": "A=contracts, B=grants, C=direct payments, D=loans"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 10
          }
        }
      },
      "RecipientsSearchRequest": {
        "type": "object",
        "required": [
          "keyword"
        ],
        "properties": {
          "keyword": {
            "type": "string",
            "description": "Recipient name fragment"
          },
          "award_type_codes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 10
          }
        }
      },
      "Award": {
        "type": "object",
        "properties": {
          "award_id": {
            "type": "string",
            "nullable": true
          },
          "recipient_name": {
            "type": "string",
            "nullable": true
          },
          "award_amount_usd": {
            "type": "number",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "awarding_agency": {
            "type": "string",
            "nullable": true
          },
          "awarding_sub_agency": {
            "type": "string",
            "nullable": true
          },
          "funding_agency": {
            "type": "string",
            "nullable": true
          },
          "period_start": {
            "type": "string",
            "nullable": true
          },
          "period_end": {
            "type": "string",
            "nullable": true
          },
          "award_type": {
            "type": "string",
            "nullable": true
          },
          "internal_id": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "AwardsResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "endpoint": {
                "type": "string"
              },
              "request_filters": {
                "type": "object"
              },
              "keyword": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              },
              "awards": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Award"
                }
              }
            }
          },
          "meta": {
            "type": "object"
          }
        }
      },
      "Agency": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "abbreviation": {
            "type": "string",
            "nullable": true
          },
          "icon_filename": {
            "type": "string",
            "nullable": true
          },
          "mission": {
            "type": "string",
            "nullable": true
          },
          "website": {
            "type": "string",
            "nullable": true
          },
          "active_fy": {
            "type": "string",
            "nullable": true
          },
          "active_fq": {
            "type": "string",
            "nullable": true
          },
          "budget_authority_amount_usd": {
            "type": "number"
          },
          "obligated_amount_usd": {
            "type": "number"
          },
          "outlay_amount_usd": {
            "type": "number"
          },
          "current_total_budget_authority_usd": {
            "type": "number"
          }
        }
      },
      "AgencyResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "agency": {
                "$ref": "#/components/schemas/Agency"
              }
            }
          }
        }
      },
      "AgencyTop": {
        "type": "object",
        "properties": {
          "agency_name": {
            "type": "string"
          },
          "agency_id": {
            "type": "integer"
          },
          "agency_code": {
            "type": "string",
            "nullable": true
          },
          "agency_slug": {
            "type": "string",
            "nullable": true
          },
          "amount_usd": {
            "type": "number"
          },
          "total_outlays_usd": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "AgenciesTopResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "fiscal_year": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              },
              "agencies": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AgencyTop"
                }
              }
            }
          }
        }
      },
      "FedRegDoc": {
        "type": "object",
        "properties": {
          "document_number": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "abstract": {
            "type": "string",
            "nullable": true
          },
          "publication_date": {
            "type": "string"
          },
          "agency_names": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "html_url": {
            "type": "string"
          },
          "pdf_url": {
            "type": "string"
          },
          "cfr_references": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "docket_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "FedRegResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string"
              },
              "query": {
                "type": "string"
              },
              "count": {
                "type": "integer"
              },
              "total": {
                "type": "integer",
                "nullable": true
              },
              "total_pages": {
                "type": "integer",
                "nullable": true
              },
              "documents": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FedRegDoc"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "core",
      "description": "liveness + version + openapi"
    },
    {
      "name": "awards",
      "description": "USAspending.gov contract awards"
    },
    {
      "name": "agencies",
      "description": "USAspending.gov federal agencies"
    },
    {
      "name": "federal-register",
      "description": "Federal Register rules + notices"
    }
  ],
  "security": [
    {
      "ApiKey": []
    },
    {
      "Bearer": []
    },
    {
      "RapidAPIProxy": []
    }
  ]
}