openapi: 3.0.3
info:
  title: OurPeople API
  description: >-
    The OurPeople API uses common standards to allow easy read and write access
    to your data. OurPeople is a frontline communications platform that helps
    organizations communicate with deskless workers. The API is currently in
    closed beta.
  contact:
    name: OurPeople Support
    email: support@ourpeople.com
    url: https://ourpeople.com/support
  version: 1.0.0
externalDocs:
  description: OurPeople Developer Documentation
  url: https://developer.ourpeople.com/
servers:
  - url: https://{account}-api.ourpeople.co
    description: Account-specific API endpoint
    variables:
      account:
        default: example
        description: >-
          Your account subdomain. If your console URL is
          https://example.ourpeople.com, then your API endpoint is
          https://example-api.ourpeople.co.
tags:
  - name: Authentication
    description: Token issuance and refresh.
  - name: Broadcasts
    description: Inspect broadcasts, deliveries, and recipient engagement.
paths:
  /v1/auth:
    post:
      tags:
        - Authentication
      summary: Exchange client credentials for a token
      description: >-
        Exchange a client ID and secret for a short-lived JWT access token and
        a long-lived refresh token.
      operationId: createToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthRequest'
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid credentials
  /v1/auth/refresh:
    post:
      tags:
        - Authentication
      summary: Refresh an access token
      description: Use a refresh token to obtain a new access token and refresh token.
      operationId: refreshToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
      responses:
        '200':
          description: Token refreshed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid or expired refresh token
  /v1/broadcasts/deliveries:
    get:
      tags:
        - Broadcasts
      summary: List recent deliveries
      description: List recent broadcast deliveries with status and basic metadata.
      operationId: listDeliveries
      security:
        - bearerAuth: []
      responses:
        '200':
          description: A list of recent deliveries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Delivery'
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
  /v1/broadcasts/{broadcastId}:
    get:
      tags:
        - Broadcasts
      summary: Get broadcast details
      description: Fetch detail on the content items attached to a broadcast.
      operationId: getBroadcast
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Broadcast detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Broadcast'
        '401':
          description: Unauthorized
        '404':
          description: Broadcast not found
  /v1/broadcasts/deliveries/{deliveryId}/recipients:
    get:
      tags:
        - Broadcasts
      summary: List delivery recipients
      description: >-
        See recipients who engaged with content in a delivery. Includes seenAt
        and respondedAt timestamps (null if the action has not occurred).
      operationId: listDeliveryRecipients
      security:
        - bearerAuth: []
      parameters:
        - name: deliveryId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of recipients for the delivery
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
        '404':
          description: Delivery not found
  /v1/broadcasts/deliveries/{deliveryId}/contents/{contentId}/recipients:
    get:
      tags:
        - Broadcasts
      summary: List content recipients
      description: >-
        Return the recipients for a given content item within a delivery.
        Supported query parameters vary by content type (e.g., rating-based
        filtering for rating content).
      operationId: listContentRecipients
      security:
        - bearerAuth: []
      parameters:
        - name: deliveryId
          in: path
          required: true
          schema:
            type: string
        - name: contentId
          in: path
          required: true
          schema:
            type: string
        - name: rating
          in: query
          required: false
          description: Filter by rating value when the content type is a rating.
          schema:
            type: integer
      responses:
        '200':
          description: A list of recipients for the content item
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recipient'
        '401':
          description: Unauthorized
        '404':
          description: Content or delivery not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    AuthRequest:
      type: object
      required:
        - id
        - secret
      properties:
        id:
          type: string
          description: Client identifier
        secret:
          type: string
          description: Client secret credential
    RefreshRequest:
      type: object
      required:
        - refresh_token
      properties:
        refresh_token:
          type: string
          description: Previously issued refresh token
    TokenResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT access token
        refresh_token:
          type: string
          description: Token used to obtain new access tokens
    Delivery:
      type: object
      properties:
        id:
          type: string
          description: Delivery identifier
        broadcastId:
          type: string
          description: Identifier of the parent broadcast
        broadcastName:
          type: string
        status:
          type: string
          description: Delivery status
    Broadcast:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        createdBy:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        createdAt:
          type: string
          format: date-time
        contents:
          type: array
          items:
            $ref: '#/components/schemas/ContentItem'
    ContentItem:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          description: The content type (e.g., text, file, rating).
    Recipient:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        seenAt:
          type: string
          format: date-time
          nullable: true
        respondedAt:
          type: string
          format: date-time
          nullable: true