openapi: 3.1.0
info:
  title: Charity Engine Distribution Partner API
  description: Endpoints of the Distribution Partner API are defined in sections below. Functions of the API can be tested directly from this document by first clicking the Authorize button to provide a valid API key and then using the "Try it out" link for the specific function.
  version: 1.0.1
servers:
  - url: https://www.charityengine.com/api/v1
tags:
  - name: installs
    description: The installs endpoint returns daily counts of Charity Engine client installs that have been received from a given source.
paths:
  /installs:
    get:
      tags:
        - installs
      parameters:
        - name: campaign
          in: query
          required: true
          description: Identifier of the campaign
          schema:
            type: string
            minLength: 1
            maxLength: 128
        - name: countries
          in: query
          required: false
          description: Comma-delimited list of two-letter ISO 3166-1 country codes, used to limit results to specific countries; use "none" as the code for installs without a country
          schema:
            type: string
            minLength: 2
            maxLength: 256
            default: all
        - name: history_days
          in: query
          required: false
          description: Number of days of history to return
          schema:
            type: integer
            default: 30
      responses:
        200:
          description: Returns counts of installs per day
          content:
            application/json:
              example:
                2024-01-01: 423
                2024-01-02: 546
                2024-01-03: 343
        404:
          description: No results found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Unknown campaign ID
        405:
          description: Missing or invalid input provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: History length cannot be less than a single day
      security:
        - tokenAuth: []

components:
  securitySchemes:
    tokenAuth:
      name: auth
      in: query
      type: apiKey
      description: >
        This API uses authentication tokens for access control. Tokens are issued
        by Charity Engine upon request. To obtain a token, contact Charity Engine
        support with your account details.

        Note: The token should be kept secure and not exposed in client-side code.