Tackle Notifications API

openapi: 3.0.3
info:
  title: Tackle Authentication Notifications API
  description: Authenticated programmatic access to Tackle's webhooks, metering, private offers, and more.
  version: 1.0.0
  contact:
    name: Tackle Support
    email: support@tackle.io
    url: https://tackle.io
servers:
- url: https://api.tackle.io
tags:
- name: Notifications
  description: Buyer instruction notification operations.
paths:
  /api/private-offers/{id}/notifications:
    post:
      tags:
      - Notifications
      summary: Create an offer notification
      description: 'Creates an offer notification. Currently only buyer instruction emails

        are supported. To send buyer instructions, use `type:

        buyer_instructions` and `channel: email`. The handler publishes through

        Tackle Notification Service and marks the offer as email sent.


        Required RBAC action: `offers:SendOfferInstructions`.

        '
      operationId: createPrivateOfferNotification
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/OfferId'
      - $ref: '#/components/parameters/TackleOperationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOfferNotificationRequest'
            examples:
              sendBuyerInstructionsEmail:
                summary: Send buyer instruction email
                value:
                  type: buyer_instructions
                  channel: email
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    OfferId:
      name: id
      in: path
      required: true
      description: Tackle private offer ID.
      schema:
        type: string
      example: po-1234
    TackleOperationId:
      name: tackle-operation-id
      in: header
      required: false
      description: Optional caller-provided operation ID for request tracing.
      schema:
        type: string
      example: 018f01ec-3f2b-7a70-b81e-4fc3d6a69f42
  responses:
    NotFoundError:
      description: Requested offer or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: not found
    ForbiddenError:
      description: Caller is not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: forbidden
    NoContent:
      description: Operation completed successfully with no response body.
    UnauthorizedError:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: unauthorized
    BadRequestError:
      description: Invalid request or unsupported operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: missing id
    InternalServerError:
      description: Internal server error or upstream dependency failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CreateOfferNotificationRequest:
      type: object
      description: 'Request body for creating an offer notification. Only buyer instruction

        emails are currently supported.

        '
      required:
      - type
      - channel
      properties:
        type:
          type: string
          enum:
          - buyer_instructions
          description: Notification type to create.
          example: buyer_instructions
        channel:
          type: string
          enum:
          - email
          description: Notification channel to use.
          example: email
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: missing id
  securitySchemes:
    BearerAuth:
      description: The Tackle API requires a JWT for authentication. You can get this by [getting your API credentials](https://developers.tackle.io/docs/how-to-get-an-m2m-client-id-and-secret) from the Tackle Platform then [retrieving your Access Token](https://developers.tackle.io/docs/getting-an-access-token) using our Authentication endpoint.
      type: http
      scheme: bearer
      bearerFormat: JWT
    BasicAuthCallback:
      description: Use `basic` for [basic HTTP authentication](https://en.wikipedia.org/wiki/Basic_access_authentication); this is only used for `callbacks`
      type: http
      scheme: basic
    HeaderApiKeyAuthCallback:
      description: Use `header_api_key` to specify a custom HTTP request header for authentication. Requests from Tackle will use the specified HTTP header for outbound requests to your Webhook URL; this is only used for `callbacks`'
      type: apiKey
      name: subscription-key
      in: header
    Oauth2AuthCallback:
      description: This auth-type is for `oauth2` client credentials flow. We will use the client_id and client_secret to call the token_url to get an access token; this is only used for `callbacks`'
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
externalDocs:
  description: Tackle Developer Hub and API Documentation
  url: https://developers.tackle.io
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true