{
  "openapi": "3.1.0",
  "info": {
    "title": "AlignMint Public Discovery & Nonprofit Data API",
    "version": "1.0.0",
    "description": "Public read-only endpoints for page Markdown, IRS Form 990 nonprofit readiness profiles, federal grant opportunities from Grants.gov, and published product roadmap items on getalignmint.org. Full AI-readable documentation is available at https://www.getalignmint.org/llms.txt and https://www.getalignmint.org/llms-full.txt.",
    "contact": {
      "name": "AlignMint Support",
      "email": "hello@getalignmint.org",
      "url": "https://www.getalignmint.org/contact"
    }
  },
  "servers": [
    {
      "url": "https://www.getalignmint.org",
      "description": "AlignMint Production Public Web & Discovery Server"
    }
  ],
  "paths": {
    "/api/markdown": {
      "get": {
        "operationId": "getPageMarkdown",
        "summary": "Render a public site page as Markdown",
        "description": "Returns the Markdown representation of a public AlignMint page. The path query selects the page. Requests without a non-empty path query return status 400. Unknown paths return Markdown with status 404. The checked-in AI index files /llms.txt and /llms-full.txt are also served by this endpoint.",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": true,
            "description": "Site pathname to render, such as /, /docs, or /blog/some-slug.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Page rendered as Markdown.",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          },
          "400": {
            "description": "The path query is absent or empty. The body is Markdown, not JSON.",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          },
          "404": {
            "description": "No published page matches the requested path. The body is Markdown, not JSON.",
            "content": {
              "text/markdown": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/api/nonprofit-health/search": {
      "get": {
        "operationId": "searchNonprofitHealthProfiles",
        "summary": "Search public nonprofit IRS 990 & readiness profiles",
        "description": "Searches public nonprofit directory profiles by organization name, two-letter US state code, or nonprofit category.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Organization name or keyword query.",
            "schema": { "type": "string", "maxLength": 120 }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Two-letter US state code (e.g. TX, CA, NY).",
            "schema": { "type": "string", "minLength": 2, "maxLength": 2 }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Nonprofit directory category slug.",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of profiles to return (1 to 50, default 20).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching nonprofit directory profiles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["profiles", "paused"],
                  "properties": {
                    "paused": { "type": "boolean" },
                    "profiles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ein": { "type": "string" },
                          "name": { "type": "string" },
                          "city": { "type": "string" },
                          "state": { "type": "string" },
                          "canonicalPath": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/nonprofit-health/ein/{ein}": {
      "get": {
        "operationId": "getNonprofitHealthProfileByEin",
        "summary": "Get a nonprofit readiness profile by EIN",
        "description": "Returns the public IRS Form 990 readiness profile for a nine-digit Employer Identification Number. Non-digit characters in the EIN are ignored.",
        "parameters": [
          {
            "name": "ein",
            "in": "path",
            "required": true,
            "description": "IRS Employer Identification Number (nine digits).",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Public nonprofit readiness profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["profile"],
                  "properties": {
                    "profile": { "$ref": "#/components/schemas/NonprofitHealthProfile" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid EIN.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "No public profile exists for this EIN.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/nonprofit-health/profile/{profileId}": {
      "get": {
        "operationId": "getNonprofitHealthProfileById",
        "summary": "Get a nonprofit readiness profile by profile id",
        "description": "Returns the public IRS Form 990 readiness profile for a nonprofit directory profile id.",
        "parameters": [
          {
            "name": "profileId",
            "in": "path",
            "required": true,
            "description": "Nonprofit directory profile id.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Public nonprofit readiness profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["profile"],
                  "properties": {
                    "profile": { "$ref": "#/components/schemas/NonprofitHealthProfile" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid profile id.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "No public profile exists for this profile id.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/nonprofit-health/domain": {
      "get": {
        "operationId": "getNonprofitHealthProfileByDomain",
        "summary": "Get a nonprofit readiness profile by website host",
        "description": "Looks up a public IRS Form 990 readiness profile from a website host or URL. The host is normalized to a lowercase hostname with any leading www. removed.",
        "parameters": [
          {
            "name": "host",
            "in": "query",
            "required": true,
            "description": "Nonprofit website host or URL, such as example.org or https://www.example.org.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Public nonprofit readiness profile for the host.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["profile"],
                  "properties": {
                    "profile": { "$ref": "#/components/schemas/NonprofitHealthProfile" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid host query parameter.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "No public profile is linked to this host.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/grants/search": {
      "get": {
        "operationId": "searchFederalGrants",
        "summary": "Search open federal grant opportunities via Grants.gov",
        "description": "Queries active posted federal grant opportunities filtered by keyword, funding category code, and page number.",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "description": "Search keyword (up to 120 characters).",
            "schema": { "type": "string", "maxLength": 120 }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Grants.gov funding category code.",
            "schema": { "type": "string" }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-indexed page number (1 to 1000).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "Grants.gov search results payload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameter.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "502": {
            "description": "Grants.gov returned an upstream error or the request failed before a response.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "504": {
            "description": "Grants.gov request timed out.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/grants/{opportunityId}": {
      "get": {
        "operationId": "getFederalGrantOpportunity",
        "summary": "Get one federal grant opportunity from Grants.gov",
        "description": "Returns the Grants.gov opportunity detail for a numeric opportunity id. Non-numeric ids are rejected. Upstream Grants.gov failures are returned as 502.",
        "parameters": [
          {
            "name": "opportunityId",
            "in": "path",
            "required": true,
            "description": "Grants.gov numeric opportunity id.",
            "schema": { "type": "string", "pattern": "^[0-9]+$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Grant opportunity detail from Grants.gov.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Grants.gov fetchOpportunity payload for the requested opportunity.",
                  "properties": {
                    "errorcode": { "type": "integer" },
                    "data": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid grant opportunity id.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "Grant opportunity was not found.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "502": {
            "description": "Grants.gov could not return the opportunity.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/roadmap/public": {
      "get": {
        "operationId": "listPublicRoadmapItems",
        "summary": "List public AlignMint product roadmap items",
        "description": "Returns published items on the AlignMint public development board.",
        "responses": {
          "200": {
            "description": "List of public roadmap items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["items"],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "title": { "type": "string" },
                          "status": { "type": "string" },
                          "category": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human- and agent-readable error message."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code."
          },
          "resolution": {
            "type": "string",
            "description": "Suggested resolution step for callers."
          }
        }
      },
      "NonprofitHealthProfile": {
        "type": "object",
        "required": ["id", "ein", "legalName", "displayName", "canonicalPath"],
        "properties": {
          "id": { "type": "string" },
          "ein": { "type": "string", "description": "Nine-digit IRS Employer Identification Number." },
          "legalName": { "type": "string" },
          "displayName": { "type": "string" },
          "slug": { "type": "string" },
          "state": { "type": ["string", "null"] },
          "city": { "type": ["string", "null"] },
          "website": { "type": ["string", "null"] },
          "websiteDomain": { "type": ["string", "null"] },
          "nteeCode": { "type": ["string", "null"] },
          "nteeCategory": { "type": ["string", "null"] },
          "canonicalPath": { "type": "string" },
          "canonicalUrl": { "type": "string" },
          "claimStatus": { "type": "string" },
          "donationStatus": { "type": "string" },
          "donationUrl": { "type": ["string", "null"] },
          "latestTaxYear": { "type": ["integer", "null"] },
          "dataQuality": { "type": "string" }
        }
      }
    }
  }
}
