openapi: 3.0.1
info:
  title: Courier Audiences Providers API
  description: The Courier REST API.
  version: ''
servers:
- url: https://api.courier.com
  description: Production
tags:
- name: Providers
paths:
  /providers:
    get:
      description: List configured provider integrations for the current workspace. Supports cursor-based pagination.
      operationId: providers_list
      tags:
      - Providers
      parameters:
      - name: cursor
        in: query
        description: Opaque cursor for fetching the next page.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvidersListResponse'
      summary: List providers
      security:
      - BearerAuth: []
    post:
      description: Create a new provider configuration. The `provider` field must be a known Courier provider key (see catalog).
      operationId: providers_create
      tags:
      - Providers
      parameters: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
      summary: Create a provider
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvidersCreateRequest'
  /providers/catalog:
    get:
      description: Returns the catalog of available provider types with their display names, descriptions, and configuration schema fields (snake_case, with `type` and `required`). Providers with no configurable schema return only `provider`, `name`, and `description`.
      operationId: providers_catalog
      tags:
      - Providers
      parameters:
      - name: keys
        in: query
        description: Comma-separated provider keys to filter by (e.g. `sendgrid,twilio`).
        required: false
        schema:
          type: string
      - name: name
        in: query
        description: Case-insensitive substring match against the provider display name.
        required: false
        schema:
          type: string
      - name: channel
        in: query
        description: Exact match (case-insensitive) against the provider channel taxonomy (e.g. `email`, `sms`, `push`).
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvidersCatalogResponse'
      summary: List available provider types
      security:
      - BearerAuth: []
  /providers/{id}:
    get:
      description: Fetch a single provider configuration by ID.
      operationId: providers_retrieve
      tags:
      - Providers
      parameters:
      - name: id
        in: path
        description: A unique identifier of the provider configuration.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      summary: Get a provider
      security:
      - BearerAuth: []
    put:
      description: Replace an existing provider configuration. The `provider` key is required and determines which provider-specific settings schema is applied. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge). Changing the provider type for an existing configuration is not supported.
      operationId: providers_update
      tags:
      - Providers
      parameters:
      - name: id
        in: path
        description: A unique identifier of the provider configuration to update.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Provider'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      summary: Update a provider
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvidersUpdateRequest'
    delete:
      description: Delete a provider configuration. Returns 409 if the provider is still referenced by routing or notifications.
      operationId: providers_delete
      tags:
      - Providers
      parameters:
      - name: id
        in: path
        description: A unique identifier of the provider configuration to delete.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Provider successfully deleted.
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
      summary: Delete a provider
      security:
      - BearerAuth: []
components:
  schemas:
    ProvidersCatalogResponse:
      title: ProvidersCatalogResponse
      type: object
      description: Paginated list of available provider types with their configuration schemas.
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/ProvidersCatalogEntry'
      required:
      - paging
      - results
    NotFound:
      title: NotFound
      type: object
      properties:
        type:
          type: string
          enum:
          - invalid_request_error
      required:
      - type
      allOf:
      - $ref: '#/components/schemas/BaseError'
    ProvidersListResponse:
      title: ProvidersListResponse
      type: object
      description: Paginated list of provider configurations.
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/Provider'
      required:
      - paging
      - results
    ProvidersCatalogEntry:
      title: ProvidersCatalogEntry
      type: object
      description: A provider type from the catalog. Contains the key, display name, description, and a `settings` object describing configuration schema fields.
      properties:
        provider:
          type: string
          description: The provider key (e.g. "sendgrid", "twilio").
        name:
          type: string
          description: Human-readable display name.
        description:
          type: string
          description: Short description of the provider.
        channel:
          type: string
          description: Courier taxonomy channel (e.g. email, push, sms, direct_message, inbox, webhook).
        settings:
          type: object
          description: Map of setting field names (snake_case) to their schema descriptors. Each descriptor has `type` and `required`. Empty when the provider has no configurable schema.
          additionalProperties:
            $ref: '#/components/schemas/ProviderSchemaField'
      required:
      - provider
      - name
      - description
      - channel
      - settings
    Conflict:
      title: Conflict
      type: object
      properties:
        type:
          type: string
          enum:
          - invalid_request_error
      required:
      - type
      allOf:
      - $ref: '#/components/schemas/BaseError'
    BadRequest:
      title: BadRequest
      type: object
      properties:
        type:
          type: string
          enum:
          - invalid_request_error
      required:
      - type
      allOf:
      - $ref: '#/components/schemas/BaseError'
    BaseError:
      title: BaseError
      type: object
      properties:
        message:
          type: string
          description: A message describing the error that occurred.
      required:
      - message
    ProvidersCreateRequest:
      title: ProvidersCreateRequest
      type: object
      description: Request body for creating a new provider configuration.
      properties:
        provider:
          type: string
          maxLength: 128
          description: The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a known Courier provider — see the catalog endpoint for valid keys.
        title:
          type: string
          description: Optional display title. Omit to use "Default Configuration".
        alias:
          type: string
          description: Optional alias for this configuration.
        settings:
          type: object
          description: Provider-specific settings (snake_case keys). Defaults to an empty object when omitted. Use the catalog endpoint to discover required fields for a given provider — omitting a required field returns a 400 validation error.
          additionalProperties: true
      required:
      - provider
    ProvidersUpdateRequest:
      title: ProvidersUpdateRequest
      type: object
      description: Request body for replacing an existing provider configuration. The `provider` key is required because it determines which provider-specific settings schema is validated against. Changing the provider type for an existing configuration is not supported. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge).
      properties:
        provider:
          type: string
          maxLength: 128
          description: The provider key identifying the type. Required on every request because it selects the provider-specific settings schema for validation.
        title:
          type: string
          description: Updated display title.
        alias:
          type: string
          description: Updated alias. Omit to clear.
        settings:
          type: object
          description: Provider-specific settings (snake_case keys). Replaces the full settings object — omitted settings fields are removed. Use the catalog endpoint to check required fields.
          additionalProperties: true
      required:
      - provider
    ProviderSchemaField:
      title: ProviderSchemaField
      type: object
      description: Describes a single configuration field in the provider catalog.
      properties:
        type:
          type: string
          description: The field's data type (e.g. "string", "boolean", "enum").
        required:
          type: boolean
          description: Whether this field is required when configuring the provider.
        values:
          type: array
          items:
            type: string
          description: Allowed values when `type` is "enum".
      required:
      - type
      - required
    Provider:
      title: Provider
      type: object
      description: A configured provider in the workspace.
      properties:
        id:
          type: string
          description: A unique identifier for the provider configuration.
        title:
          type: string
          description: Display title. Defaults to "Default Configuration" when not explicitly set.
        provider:
          type: string
          description: The provider key (e.g. "sendgrid", "twilio", "slack").
        alias:
          type: string
          description: Optional alias for this configuration.
        settings:
          type: object
          description: Provider-specific settings (snake_case keys on the wire).
          additionalProperties: true
        created:
          type: integer
          description: Unix timestamp (ms) of when the provider was created.
        updated:
          type: integer
          nullable: true
          description: Unix timestamp (ms) of when the provider was last updated.
      required:
      - id
      - title
      - provider
      - settings
      - created
    Paging:
      title: Paging
      type: object
      properties:
        cursor:
          type: string
          nullable: true
        more:
          type: boolean
      required:
      - more
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer