> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hoppier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a program

> Returns one program in the key's company.

A program in another company gets the same 404 as an id that doesn't exist.




## OpenAPI

````yaml /openapi.yaml get /programs/{program}
openapi: 3.1.0
info:
  title: Hoppier API
  version: 1.0.0-beta
  summary: Read your Hoppier programs and add people to them.
  description: >
    The Hoppier API is in **closed beta**. Everything in this reference runs in
    production today.


    - API keys are issued by Hoppier during the beta. Email
    [support@hoppier.com](mailto:support@hoppier.com) to request one.

    - There is no sandbox. Every key works against your live account.

    - We add fields and error codes without notice, so ignore anything you don't
    recognise. We don't rename or remove a documented field without announcing
    it on the [changelog](https://docs.hoppier.com/changelog) first.
  termsOfService: https://www.hoppier.com/terms
  contact:
    name: Hoppier support
    email: support@hoppier.com
servers:
  - url: https://app.hoppier.com/api/v1
    description: Production
security:
  - apiKey: []
tags:
  - name: Account
    description: Check an API key and see which account it belongs to.
  - name: Programs
    description: Read the reward programs in your account.
  - name: Participants
    description: Add people to a program.
paths:
  /programs/{program}:
    get:
      tags:
        - Programs
      summary: Get a program
      description: >
        Returns one program in the key's company.


        A program in another company gets the same 404 as an id that doesn't
        exist.
      operationId: getProgram
      parameters:
        - $ref: '#/components/parameters/ProgramPath'
      responses:
        '200':
          description: The program.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Program'
              example:
                id: prg_Z8q3NnW2xK
                object: program
                name: Team lunch
                amount: 2500
                currency: usd
                status: active
                startDate: '1793491200000'
                endDate: '1795996800000'
                createdAt: '1792504992000'
                updatedAt: '1792504992000'
                addressId: ad_7Ym2p0Lx3Q
                colorHex: '#FF6161'
                colorHex2: '#FFFFFF'
                logoUrl: null
        '400':
          description: >
            The API key is missing or malformed, or the program id isn't a
            `prg_` id. On an id error, `parameter` holds the value you sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                badId:
                  summary: Not a program id
                  value:
                    message: invalid program ID
                    parameter: pcpt_R4k1LmQ8vB
                missingKey:
                  summary: No API key
                  value:
                    message: API key is missing
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ProgramNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    ProgramPath:
      name: program
      in: path
      required: true
      description: The program's id. Starts with `prg_`.
      schema:
        type: string
        pattern: ^prg_
      example: prg_Z8q3NnW2xK
  schemas:
    Program:
      type: object
      description: A reward program in your account.
      required:
        - id
        - object
        - name
        - amount
        - currency
        - status
        - startDate
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: The program's id. Starts with `prg_`.
          examples:
            - prg_Z8q3NnW2xK
        object:
          type: string
          const: program
        name:
          type: string
          examples:
            - Team lunch
        amount:
          type: integer
          description: >
            The amount each person gets, in **cents** (`2500` means \$25.00).
            `0` on a program where each person has their own amount.
          examples:
            - 2500
        currency:
          type: string
          description: Lowercase currency code. `usd` is the only value today.
          examples:
            - usd
        status:
          type: string
          enum:
            - active
            - inactive
            - pending
          description: |
            `active`: running. `inactive`: archived. `pending`: not active yet.
        startDate:
          type: string
          description: >
            When the program starts: a Unix timestamp in **milliseconds**, as a
            string. A program with no start date returns the string
            `"undefined"`, so treat anything that isn't 13 digits as "no start
            date".
          examples:
            - '1793491200000'
        endDate:
          type: string
          description: >-
            When the program ends (Unix milliseconds, as a string). Left out
            when the program has no end date.
          examples:
            - '1795996800000'
        createdAt:
          type: string
          description: Unix milliseconds, as a string.
          examples:
            - '1792504992000'
        updatedAt:
          type: string
          description: Unix milliseconds, as a string.
          examples:
            - '1792504992000'
        addressId:
          type: string
          description: Id of the program's address. Starts with `ad_`.
          examples:
            - ad_7Ym2p0Lx3Q
        colorHex:
          type:
            - string
            - 'null'
          description: The program's main colour in the Hoppier app.
          examples:
            - '#FF6161'
        colorHex2:
          type:
            - string
            - 'null'
          description: The program's second colour in the Hoppier app.
          examples:
            - '#FFFFFF'
        logoUrl:
          type:
            - string
            - 'null'
          description: URL of the program's logo, if it has one.
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: What went wrong, in plain words. Don't parse it; it can change.
        error:
          type: string
          description: >
            A machine-readable code. Present on some errors today
            (`rate_limited`, `rate_limit_unavailable`, `in_progress`,
            `idempotency_key_reuse`, `request_outcome_unknown`), and on every
            error after the next API update.
        parameter:
          type: string
          description: >-
            On some validation errors, the field (or the value) that was
            refused.
        code:
          type: string
          description: >-
            Only on the 402 `send_credits_exhausted` response today. It moves to
            `error` in the next API update.
  responses:
    Unauthorized:
      description: The API key is wrong, unknown or switched off.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidKey:
              summary: Wrong or unknown key
              value:
                message: user is unauthorized
            inactiveKey:
              summary: Key switched off
              value:
                message: API key is inactive
    ProgramNotFound:
      description: >-
        No program with this id in the key's company. A program in another
        company gets the same answer.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: program prg_Z8q3NnW2xK not found
    RateLimited:
      description: >
        Too many requests. Wait the number of seconds in `Retry-After`, then
        retry. The per-account limit answers in JSON; the per-address limit
        answers in plain text today and can send a fraction of a second, so
        round it up. See [Errors and rate
        limits](/guides/errors-and-rate-limits).
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: rate_limited
            message: >-
              Too many requests for this account. Retry after the number of
              seconds in Retry-After.
        text/plain:
          schema:
            type: string
          example: Too Many Requests
    ServerError:
      description: >
        Something went wrong on Hoppier's side. Retry with backoff; if it keeps
        happening, email support@hoppier.com. Today `message` can contain
        internal text: log it, but don't show it to your users.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: An unexpected error occurred.
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: string
      example: '30'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: hk_live.<prefix>.<secret>
      description: >
        Send your key in the `Authorization` header: `Authorization: Bearer
        hk_live.…`. The word `Bearer` is case-sensitive.


        Keys are issued by Hoppier during the beta and shown once. Treat them
        like passwords and never put one in code that runs in a browser or an
        app.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.