openapi: 3.1.0

info:
  title: Benefits Wayfinder Partner API
  version: 1.0.0
  description: >
    Provides approved partner organizations with secure access to published
    Benefits Wayfinder content.

servers:
  - url: https://hub.benefitswayfinder.org
    description: Production
  - url: http://localhost:3000
    description: Local development

tags:
  - name: Benefits
    description: Published Benefits Wayfinder benefits

paths:
  /api/v1/benefits:
    get:
      tags:
        - Benefits
      summary: List benefits
      description: >
        Returns published Benefits Wayfinder benefits. Results can be filtered
        by province and city and returned in English or French.
      operationId: listBenefits
      security:
        - ApiKeyAuth: []

      parameters:
        - name: lang
          in: query
          required: false
          description: Language used for localized content.
          schema:
            type: string
            enum:
              - en
              - fr
            default: en

        - name: province
          in: query
          required: false
          description: >
            Canadian province or territory code. Use CA for federal benefits.
          schema:
            type: string
            example: ON

        - name: city
          in: query
          required: false
          description: City name.
          schema:
            type: string
            example: Waterloo

        - name: limit
          in: query
          required: false
          description: Number of records to return.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100

        - name: offset
          in: query
          required: false
          description: Number of records to skip.
          schema:
            type: integer
            minimum: 0
            default: 0

      responses:
        "200":
          description: Benefits returned successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BenefitListResponse"
              examples:
                success:
                  summary: Ontario benefits
                  value:
                    version: "1.0"
                    total: 61
                    limit: 2
                    offset: 0
                    lang: en
                    items:
                      - id: 68yNZ7Uy67GiOxt7GgKS3L
                        title: Affordable Food
                        slug: affordable-food
                        acronym: null
                        provinceCode: ON
                        authority: Ontario
                        city: Waterloo
                        lead: >
                          If you live in the Region of Waterloo and are
                          struggling to provide food for your household...
                        headlineValue: null
                        introduction: Markdown content may be included.
                        eligibility: Eligibility information may be included.
                        howToApply: Application instructions may be included.
                        taxFilingUnlocks: false
                        taxFilingApplication: false
                        taxFilingAndApplication: false
                        categories:
                          - id: 10jjQrukVoc4DvK2DzYbV0
                            title: General
                        requiredIdentification: []
                        sourceUpdatedAt: "2026-02-09T14:09:22.595Z"

        "401":
          description: API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Invalid API key

        "403":
          description: API key is disabled or expired, or partner access is disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: API key is disabled

        "500":
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error: Internal server error

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Partner API key issued by Prosper Canada.

  schemas:
    BenefitListResponse:
      type: object
      required:
        - version
        - total
        - limit
        - offset
        - lang
        - items
      properties:
        version:
          type: string
          example: "1.0"

        total:
          type: integer
          example: 61

        limit:
          type: integer
          example: 100

        offset:
          type: integer
          example: 0

        lang:
          type: string
          enum:
            - en
            - fr

        items:
          type: array
          items:
            $ref: "#/components/schemas/Benefit"

    Benefit:
      type: object
      required:
        - id
        - title
        - slug
        - provinceCode
        - categories
        - requiredIdentification
        - sourceUpdatedAt
      properties:
        id:
          type: string
          description: Stable Benefits Wayfinder entry identifier.
          example: 68yNZ7Uy67GiOxt7GgKS3L

        title:
          type: string
          example: Affordable Food

        slug:
          type: string
          example: affordable-food

        acronym:
          type:
            - string
            - "null"
          example: null

        provinceCode:
          type:
            - string
            - "null"
          example: ON

        authority:
          type:
            - string
            - "null"
          example: Ontario

        city:
          type:
            - string
            - "null"
          example: Waterloo

        lead:
          type:
            - string
            - "null"

        headlineValue:
          type:
            - string
            - "null"

        introduction:
          type:
            - string
            - "null"
          description: May contain Markdown.

        eligibility:
          type:
            - string
            - "null"
          description: May contain Markdown.

        howToApply:
          type:
            - string
            - "null"
          description: May contain Markdown.

        taxFilingUnlocks:
          type: boolean

        taxFilingApplication:
          type: boolean

        taxFilingAndApplication:
          type: boolean

        categories:
          type: array
          items:
            $ref: "#/components/schemas/Category"

        requiredIdentification:
          type: array
          items:
            $ref: "#/components/schemas/Identification"

        sourceUpdatedAt:
          type: string
          format: date-time
          description: ISO 8601 UTC timestamp from the source content.

    Category:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: string
        title:
          type: string

    Identification:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string

        name:
          type: string

        details:
          type:
            - string
            - "null"
          description: May contain Markdown.

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string