openapi: 3.1.0
info:
  title: GiveRadar API
  description: |
    Access integrity assessments, financial data, officers, and contact information for 7.9 million+ nonprofits across 100+ countries.

    ## Authentication
    All requests require an API key. Get your free key at [giveradar.com/api/keys/](https://giveradar.com/api/keys/).

    Pass your key as:
    - **Header:** `Authorization: Bearer gr_your_key_here`
    - **Query param:** `?api_key=gr_your_key_here`

    ## Rate Limits
    | Tier | Requests/day | Price |
    |------|-------------|-------|
    | Free | 10 | $0/month |
    | Pro | 10,000 | $99/month |
    | Enterprise | 100,000 | Custom |
  version: "1.0.0"
  contact:
    name: GiveRadar
    email: info@giveradar.com
    url: https://giveradar.com
  license:
    name: Proprietary
    url: https://giveradar.com/terms/
  termsOfService: https://giveradar.com/terms/

servers:
  - url: https://giveradar.com/api/v1
    description: Production

security:
  - bearerAuth: []
  - apiKeyQuery: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key as Bearer token: `Authorization: Bearer gr_xxxxx`"
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: "API key as query parameter: `?api_key=gr_xxxxx`"

  schemas:
    CharitySummary:
      type: object
      properties:
        slug:
          type: string
          example: "american-national-red-cross"
        name:
          type: string
          example: "American National Red Cross"
        country_code:
          type: string
          example: "US"
        trust_score:
          type: integer
          nullable: true
          example: 82
        annual_revenue:
          type: integer
          nullable: true
          example: 3200000000
        program_spend_pct:
          type: number
          nullable: true
          example: 89.2
        category:
          type: string
          nullable: true
          example: "Human Services"
        verified:
          type: boolean
          example: true

    CharityDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        country_code:
          type: string
        description:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        founded_year:
          type: integer
          nullable: true
        website:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state_province:
          type: string
          nullable: true
        ein:
          type: string
          nullable: true
        uk_charity_number:
          type: string
          nullable: true
        registration_number:
          type: string
          nullable: true
        annual_revenue:
          type: integer
          nullable: true
        annual_expenses:
          type: integer
          nullable: true
        program_expenses:
          type: integer
          nullable: true
        admin_expenses:
          type: integer
          nullable: true
        fundraising_expenses:
          type: integer
          nullable: true
        overhead_ratio:
          type: number
          nullable: true
        program_spend_pct:
          type: number
          nullable: true
        top_exec_name:
          type: string
          nullable: true
        top_exec_title:
          type: string
          nullable: true
        top_exec_compensation:
          type: integer
          nullable: true
        employee_count:
          type: integer
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        address:
          type: string
          nullable: true
        donation_url:
          type: string
          nullable: true
        mission_statement:
          type: string
          nullable: true
        logo_url:
          type: string
          nullable: true
        twitter_url:
          type: string
          nullable: true
        facebook_url:
          type: string
          nullable: true
        instagram_url:
          type: string
          nullable: true
        linkedin_url:
          type: string
          nullable: true
        youtube_url:
          type: string
          nullable: true
        trust_score:
          type: integer
          nullable: true
        data_completeness:
          type: integer
        verified:
          type: boolean
        sanctions_status:
          type: string
          nullable: true
          enum: [clear, matched]
        charity_navigator_score:
          type: number
          nullable: true
        charity_navigator_rating:
          type: integer
          nullable: true
        guidestar_seal:
          type: string
          nullable: true
        cause_tags:
          type: array
          items:
            type: string
        operating_countries:
          type: array
          items:
            type: string
        sdg_goals:
          type: array
          items:
            type: string
        data_sources:
          type: array
          items:
            type: string
        last_updated:
          type: string
          format: date-time
        recent_filings:
          type: array
          items:
            $ref: '#/components/schemas/Filing'
        officers:
          type: array
          items:
            $ref: '#/components/schemas/Officer'
        red_flags:
          type: array
          items:
            $ref: '#/components/schemas/RedFlag'
        review_summary:
          $ref: '#/components/schemas/ReviewSummary'

    Filing:
      type: object
      properties:
        fiscal_year:
          type: integer
          example: 2023
        total_revenue:
          type: integer
          example: 3200000000
        total_expenses:
          type: integer
          example: 2900000000
        program_expenses:
          type: integer
          nullable: true
        admin_expenses:
          type: integer
          nullable: true
        fundraising_expenses:
          type: integer
          nullable: true
        total_assets:
          type: integer
          nullable: true
        total_liabilities:
          type: integer
          nullable: true
        source:
          type: string
          example: "irs_990"

    Officer:
      type: object
      properties:
        name:
          type: string
          example: "Gail McGovern"
        title:
          type: string
          example: "President & CEO"
        compensation:
          type: integer
          nullable: true
          example: 694000
        fiscal_year:
          type: integer
          nullable: true
          example: 2023

    RedFlag:
      type: object
      properties:
        flag_type:
          type: string
          example: "high_exec_pay"
        severity:
          type: string
          enum: [warning, critical]
        description:
          type: string
        active:
          type: boolean

    ReviewSummary:
      type: object
      properties:
        count:
          type: integer
          example: 24
        avg_rating:
          type: number
          nullable: true
          example: 4.2

    NewsArticle:
      type: object
      properties:
        title:
          type: string
        url:
          type: string
        source_domain:
          type: string
        tone:
          type: number
          nullable: true
        published_at:
          type: string
          format: date-time

    Error:
      type: object
      properties:
        detail:
          type: string

paths:
  /search/:
    get:
      summary: Search charities
      description: Search charities by name, EIN, or country code. Returns up to 30 results sorted by trust score and revenue.
      operationId: searchCharities
      tags: [Search]
      parameters:
        - name: q
          in: query
          description: Search query (charity name or EIN)
          schema:
            type: string
          example: "red cross"
        - name: country
          in: query
          description: 2-letter country code
          schema:
            type: string
          example: "US"
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  query:
                    type: string
                  country:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CharitySummary'
        '401':
          description: API key missing
        '429':
          description: Rate limit exceeded

  /charity/{slug}/:
    get:
      summary: Get charity details
      description: Get full charity profile including financials, officers, red flags, and review summary.
      operationId: getCharity
      tags: [Charities]
      parameters:
        - name: slug
          in: path
          required: true
          description: Charity URL slug
          schema:
            type: string
          example: "american-national-red-cross"
      responses:
        '200':
          description: Full charity details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CharityDetail'
        '404':
          description: Charity not found

  /charity/{slug}/financials/:
    get:
      summary: Get financial filings
      description: Get up to 10 years of financial filing history plus spending breakdown and executive compensation.
      operationId: getCharityFinancials
      tags: [Charities]
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Financial data
          content:
            application/json:
              schema:
                type: object
                properties:
                  filings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Filing'
                  spending_breakdown:
                    type: object
                    properties:
                      program_spend_pct:
                        type: number
                      admin_spend_pct:
                        type: number
                      annual_expenses:
                        type: integer
                      annual_revenue:
                        type: integer
                  executive_compensation:
                    type: object
                    properties:
                      name:
                        type: string
                      title:
                        type: string
                      compensation:
                        type: integer

  /charity/{slug}/news/:
    get:
      summary: Get news and sentiment
      description: Get recent news articles and average sentiment score for a charity.
      operationId: getCharityNews
      tags: [Charities]
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: News articles and sentiment
          content:
            application/json:
              schema:
                type: object
                properties:
                  articles:
                    type: array
                    items:
                      $ref: '#/components/schemas/NewsArticle'
                  article_count:
                    type: integer
                  average_tone:
                    type: number
                    nullable: true

  /charity/{slug}/reviews/:
    post:
      summary: Submit a review
      description: Submit a review for a charity.
      operationId: createReview
      tags: [Reviews]
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_name, rating, title]
              properties:
                user_name:
                  type: string
                  example: "John Doe"
                user_role:
                  type: string
                  enum: [donor, volunteer, beneficiary, employee, other]
                  example: "donor"
                rating:
                  type: integer
                  minimum: 1
                  maximum: 5
                  example: 4
                title:
                  type: string
                  example: "Great organization"
                comment:
                  type: string
                  example: "Very transparent about their spending."
      responses:
        '201':
          description: Review created
        '400':
          description: Invalid input

  /stats/:
    get:
      summary: Platform statistics
      description: Get platform-wide statistics including total charities, countries, and average trust score.
      operationId: getStats
      tags: [Platform]
      responses:
        '200':
          description: Platform stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_charities:
                    type: integer
                    example: 9100000
                  total_countries:
                    type: integer
                    example: 60
                  total_red_flags:
                    type: integer
                  avg_trust_score:
                    type: number
                    nullable: true

tags:
  - name: Search
    description: Search and discover charities
  - name: Charities
    description: Detailed charity data
  - name: Reviews
    description: User reviews
  - name: Platform
    description: Platform-wide statistics
