beehiiv Automations API

openapi: 3.1.0
info:
  title: API Reference
  version: 1.0.0
paths:
  /publications/{publicationId}/advertisement_opportunities:
    get:
      operationId: index
      summary: 'Get advertisement opportunities <Badge intent="info" minimal outlined>OAuth Scope: posts:read</Badge>'
      description: Retrieve a list of accepted advertisement opportunities for the publication.
      tags:
        - subpackage_advertisement_opportunities
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_advertisement_opportunities:AdvertisementOpportunitiesGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/authors:
    get:
      operationId: index
      summary: List authors
      description: Retrieve a list of authors available for the publication.
      tags:
        - subpackage_authors
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is
            10.
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the number of results specified by the `limit`
            (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
        - name: name
          in: query
          description: Optionally filter authors by full name or first name (case-insensitive).
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_authors:AuthorsListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/authors/{authorId}:
    get:
      operationId: show
      summary: Get author
      description: Retrieve a single author from a publication.
      tags:
        - subpackage_authors
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: authorId
          in: path
          description: The author identifier. This accepts author UUID, full name, or first name.
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_authors:AuthorsGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/automations/{automationId}/journeys:
    post:
      operationId: create
      summary: 'Add subscription to an automation <Badge intent="info" minimal outlined>OAuth Scope: automations:write</Badge>'
      description: >-
        Add an existing subscription to an automation flow. Requires the automation to have an active *Add by API*
        trigger. The specified `email` or `subscription_id` will be matched against your existing subscribers. If an
        existing subscriber is found, they will be enrolled immediately.

        Looking to enroll new subscribers? Use the **[Create Subscription](/api-reference/subscriptions/create)**
        endpoint instead and specify the `automation_ids` param.
      tags:
        - subpackage_automationJourneys
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:AutomationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_automationJourneys:AutomationJourneysResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The email address associated with the subscription.
                subscription_id:
                  $ref: '#/components/schemas/type_ids:SubscriptionId'
                double_opt_override:
                  $ref: '#/components/schemas/type_:DoubleOptOverride'
                  description: >-
                    Override the publication's default double opt-in settings for this subscription. Possible values
                    are:

                    - "on" — The subscriber will receive a double opt-in confirmation email and will need to confirm
                    their subscription prior to being marked as active.

                    - "off" — The subscriber will be marked as active immediately and will not receive a double opt-in
                    confirmation email.

                    - "not_set" — The publication's default double opt-in settings will be applied to this subscription.
    get:
      operationId: index
      summary: 'List automation journeys <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>'
      description: Retrieve a list of automation journeys that have occurred within a specific automation.
      tags:
        - subpackage_automationJourneys
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:AutomationId'
        - name: status
          in: query
          description: Optionally filter the results by the automation journey's status.
          required: false
          schema:
            $ref: '#/components/schemas/type_automationJourneys:AutomationJourneysGetRequestStatus'
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is
            10.
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the number of results specified by the `limit`
            (default: 10).
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_automationJourneys:AutomationJourneysIndexResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/automations/{automationId}/journeys/{automationJourneyId}:
    get:
      operationId: show
      summary: 'Get automation journey <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>'
      description: Retrieve a single automation journey by ID.
      tags:
        - subpackage_automationJourneys
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:AutomationId'
        - name: automationJourneyId
          in: path
          description: The prefixed automation journey id
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:AutomationJourneyId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_automationJourneys:AutomationJourneysResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/automations:
    get:
      operationId: index
      summary: 'List automations <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>'
      description: Retrieve automations for a publication.
      tags:
        - subpackage_automations
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: expand[]
          in: query
          description: Optional list of expandable objects.
          required: false
          schema:
            $ref: '#/components/schemas/type_automations:AutomationsListRequestExpandItem'
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is
            10.
          required: false
          schema:
            type: integer
        - name: page
          in: query
          description: >-
            Pagination returns the results in pages. Each page contains the number of results specified by the `limit`
            (default: 10).<br>If not specified, results 1-10 from page 1 will be returned.
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_automations:AutomationsListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/automations/{automationId}:
    get:
      operationId: show
      summary: 'Get automation <Badge intent="info" minimal outlined>OAuth Scope: automations:read</Badge>'
      description: Retrieve a single automation for a publication.
      tags:
        - subpackage_automations
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:AutomationId'
        - name: expand[]
          in: query
          description: Optional list of expandable objects.
          required: false
          schema:
            $ref: '#/components/schemas/type_automations:AutomationsGetRequestExpandItem'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_automations:AutomationsGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/automations/{automationId}/emails:
    get:
      operationId: list-emails
      summary: List automation emails
      description: Retrieve all emails belonging to a specific automation, including engagement statistics for each email.
      tags:
        - subpackage_automations
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: automationId
          in: path
          description: The prefixed ID of the automation object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:AutomationId'
        - name: limit
          in: query
          description: >-
            A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is
            10.
          required: false
          schema:
            type: integer
        - name: cursor
          in: query
          description: >-
            **Cursor-based pagination (recommended)**: Use this opaque cursor token to fetch the next page of results.
            Obtain it from the `next_cursor` field of a previous response.
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: '**Deprecated**: Use `cursor` instead. Pagination returns the results in pages. Limited to 100 pages maximum.'
          required: false
          schema:
            type: integer
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_automations:AutomationEmailsListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/bulk_subscriptions:
    post:
      operationId: create
      summary: 'Bulk create subscription <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>'
      description: Create new subscriptions for a publication.
      tags:
        - subpackage_bulk_subscriptions
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subscriptions created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_bulk_subscriptions:BulkSubscriptionCreateResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptions:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_:SubscriptionRequest'
              required:
                - subscriptions
  /publications/{publicationId}/bulk_subscription_updates:
    get:
      operationId: index
      summary: 'List subscription updates <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>'
      description: Returns a list of Subscription Update objects for a publication.
      tags:
        - subpackage_bulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/bulk_subscription_updates/{id}:
    get:
      operationId: show
      summary: 'Get subscription update <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:read</Badge>'
      description: Returns a single Subscription Update object for a publication.
      tags:
        - subpackage_bulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: id
          in: path
          description: The ID of the Subscription Update object
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_bulkSubscriptionUpdates:BulkSubscriptionUpdatesGetResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
  /publications/{publicationId}/subscriptions/bulk_actions:
    put:
      operationId: put
      summary: 'Update subscriptions <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>'
      description: Bulk update multiple subscriptions fields, including status, custom fields, and tiers.
      tags:
        - subpackage_bulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_subscriptions:SubscriptionsPatchResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptions:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItem'
                  description: An array of objects representing the subscriptions to be updated (max 1000).
    patch:
      operationId: patch
      summary: 'Update subscriptions <Badge intent="info" minimal outlined>OAuth Scope: subscriptions:write</Badge>'
      description: Bulk update multiple subscriptions fields, including status, custom fields, and tiers.
      tags:
        - subpackage_bulkSubscriptionUpdates
      parameters:
        - name: publicationId
          in: path
          description: The prefixed ID of the publication object
          required: true
          schema:
            $ref: '#/components/schemas/type_ids:PublicationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_subscriptions:SubscriptionsPatchResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '429':
          description: Rate Limit Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_:Error'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                subscriptions:
                  type: array
                  items:
                    $ref: '#/components/schemas/type_bulkSubscriptionUpdates:SubscriptionsPatchRequestSubscriptionsItem'
                  

# --- truncated at 32 KB (370 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/beehiiv/refs/heads/main/openapi/beehiiv-openapi.yml