openapi: 3.0.0
info:
  title: Charity API
  description: |
    API for searching and retrieving charity information from the database.
    This API provides two main endpoints:
    1. Get all charities with pagination
    2. Search charities by name, city, state, or EIN
    
    Perfect for ChatGPT Custom GPTs and AI assistants.
  version: 1.0.0
  contact:
    name: Charity API Support

servers:
  - url: https://mcp.illumemedia.app
    description: Production server
  - url: http://localhost:8000
    description: Local development server

paths:
  /api.php:
    get:
      summary: Get or search charities
      description: |
        Main API endpoint that handles both getting all charities and searching.
        Use the 'action' parameter to specify which operation to perform.
      operationId: getOrSearchCharities
      parameters:
        - name: action
          in: query
          required: true
          description: Action to perform
          schema:
            type: string
            enum:
              - get_charities
              - search_charities
              - test
          example: get_charities
        
        # Pagination parameters
        - name: page
          in: query
          required: false
          description: Page number (starts at 1)
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
        
        - name: perPage
          in: query
          required: false
          description: Number of records per page (maximum 1000)
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 50
          example: 50
        
        # Search parameters
        - name: name
          in: query
          required: false
          description: Search by charity name (partial match, case-insensitive)
          schema:
            type: string
          example: Red Cross
        
        - name: city
          in: query
          required: false
          description: Filter by city name (partial match, case-insensitive)
          schema:
            type: string
          example: New York
        
        - name: state
          in: query
          required: false
          description: Filter by US state abbreviation (2-letter code, exact match, case-insensitive)
          schema:
            type: string
            pattern: '^[A-Z]{2}$'
            maxLength: 2
          example: CA
        
        - name: ein
          in: query
          required: false
          description: Search by EIN (Employer Identification Number) - exact match, 9 digits
          schema:
            type: string
            pattern: '^\d{9}$'
          example: "123456789"
      
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  urban_data:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: Charity name
                          example: "American Red Cross"
                        ein:
                          type: string
                          description: Employer Identification Number
                          example: "530196605"
                        city:
                          type: string
                          description: City name
                          example: "Washington"
                        state:
                          type: string
                          description: State abbreviation
                          example: "DC"
                        zip:
                          type: string
                          description: ZIP code
                          example: "20006"
                  meta:
                    type: object
                    properties:
                      totalRecords:
                        type: integer
                        description: Total number of records
                        example: 1000
                      currentPage:
                        type: integer
                        description: Current page number
                        example: 1
                      perPage:
                        type: integer
                        description: Records per page
                        example: 50
                      totalPages:
                        type: integer
                        description: Total number of pages
                        example: 20
                      filters:
                        type: object
                        description: Applied filters (only for search_charities)
                        properties:
                          name:
                            type: string
                            nullable: true
                          city:
                            type: string
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          ein:
                            type: string
                            nullable: true
                  errors:
                    type: string
                    nullable: true
                    description: Error message if any
              examples:
                get_charities:
                  summary: Get charities response
                  value:
                    success: true
                    urban_data:
                      - name: "American Red Cross"
                        ein: "530196605"
                        city: "Washington"
                        state: "DC"
                        zip: "20006"
                    meta:
                      totalRecords: 1000
                      currentPage: 1
                      perPage: 50
                      totalPages: 20
                    errors: null
                
                search_charities:
                  summary: Search charities response
                  value:
                    success: true
                    urban_data:
                      - name: "American Red Cross"
                        ein: "530196605"
                        city: "Washington"
                        state: "DC"
                        zip: "20006"
                    meta:
                      totalRecords: 5
                      currentPage: 1
                      perPage: 50
                      totalPages: 1
                      filters:
                        name: "Red Cross"
                        city: null
                        state: null
                        ein: null
                    errors: null
        
        '400':
          description: Bad request (missing required parameters or invalid input)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  errors:
                    type: string
                    example: "At least one filter parameter (name, city, state, or ein) must be provided"
                  urban_data:
                    type: array
                    example: []
                  meta:
                    type: object
                    nullable: true
                    example: null
        
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  errors:
                    type: string
                    example: "API request failed: Connection timeout"
                  urban_data:
                    type: array
                    example: []
                  meta:
                    type: object
                    nullable: true
                    example: null

  /api.php:
    post:
      summary: Get or search charities (POST method)
      description: |
        Same as GET but accepts parameters in POST body.
        Useful for ChatGPT and other services that prefer POST requests.
      operationId: getOrSearchCharitiesPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
              properties:
                action:
                  type: string
                  enum:
                    - get_charities
                    - search_charities
                    - test
                  example: search_charities
                page:
                  type: integer
                  minimum: 1
                  default: 1
                perPage:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 50
                name:
                  type: string
                city:
                  type: string
                state:
                  type: string
                ein:
                  type: string
            examples:
              search:
                summary: Search example
                value:
                  action: search_charities
                  name: "Red Cross"
                  state: "CA"
                  page: 1
                  perPage: 10
              get:
                summary: Get all example
                value:
                  action: get_charities
                  page: 1
                  perPage: 50
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharityResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    CharityResponse:
      type: object
      properties:
        success:
          type: boolean
        urban_data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              ein:
                type: string
              city:
                type: string
              state:
                type: string
              zip:
                type: string
        meta:
          type: object
          properties:
            totalRecords:
              type: integer
            currentPage:
              type: integer
            perPage:
              type: integer
            totalPages:
              type: integer
            filters:
              type: object
              nullable: true
        errors:
          type: string
          nullable: true
    
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        errors:
          type: string
        urban_data:
          type: array
          example: []
        meta:
          type: object
          nullable: true
          example: null