Tackle.io Notifications API

openapi: 3.2.0
info:
  title: Tackle Public Contracts Authentication Notifications API
  description: "Customer-facing read API for cloud marketplace contracts that Tackle has\ningested for your Tackle account.\n\nThe response shape is a stable projection of the underlying\ncontract document. It is intended to be safe to consume long-term: fields\nwill be added over time, but documented fields will not be removed without\ndeprecation notice.\n\n## Authentication\n\nEvery request must include a valid Tackle JWT in the `Authorization`\nheader (`Authorization: Bearer <token>`). Machine-to-machine (MTM) tokens\nissued for your Tackle account are accepted. The token scopes every\nresponse to the account it represents.\n\n## Pagination\n\n`GET /api/contracts` is the only paginated endpoint. Pagination uses an\nopaque `cursor` query parameter:\n\n1. The first request omits `cursor`.\n2. If more pages exist, the response includes a `next` field. Pass that\n   value verbatim back as `cursor` on the next request.\n3. The last page omits `next`.\n\nCursors are opaque tokens. Do not parse, modify, or persist them across\nschema changes — request a fresh page from the start instead.\n"
  version: 1.0.0
servers:
- url: https://contracts.tackle.io
  description: Production
security:
- tackleJwt: []
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:
  responses:
    InternalServerError:
      description: Internal server error or upstream dependency failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequestError:
      description: Invalid request or unsupported operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: missing id
    ForbiddenError:
      description: Caller is not allowed to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: forbidden
    NotFoundError:
      description: Requested offer or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: not found
    UnauthorizedError:
      description: Authentication failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: unauthorized
    NoContent:
      description: Operation completed successfully with no response body.
  schemas:
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: missing id
    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
  parameters:
    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
    OfferId:
      name: id
      in: path
      required: true
      description: Tackle private offer ID.
      schema:
        type: string
      example: po-1234
  securitySchemes:
    tackleJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Tackle-issued JWT (interactive user or MTM token).