iZap.ai Business Library API

openapi: 3.2.0
info:
  contact:
    email: support@izap.ai
    name: iZap API Support
  description: Public REST API for the iZap WhatsApp business messaging platform.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  title: iZap Business Library API
  version: v1
servers:
- description: Production
  url: https://api.izap.ai
- description: Staging
  url: https://api-staging.izap.ai
tags:
- description: Reusable images belonging to the caller's business, referenced when composing messages.
  name: business-library
paths:
  /api/v1/businesses/library/documents:
    get:
      description: Returns the library documents and videos of the authenticated user's business, newest first, paged with `limit` and `offset`.
      operationId: listBusinessLibraryDocuments
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLibraryDocumentListResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: List library documents
      tags:
      - business-library
    post:
      description: Uploads a document or video to the library of the authenticated user's business so it can later be attached to messages. PDF, DOCX and MP4 are accepted; the type is read from the file's content, not its name.
      operationId: uploadBusinessLibraryDocument
      parameters:
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_business_library_document_for_current_business_api_v1_businesses_library_documents_post'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLibraryImageOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Upload a library document
      tags:
      - business-library
  /api/v1/businesses/library/documents/{document_id}:
    delete:
      description: Removes a document from the library. Messages already sent that referenced it are unaffected.
      operationId: deleteBusinessLibraryDocument
      parameters:
      - in: path
        name: document_id
        required: true
        schema:
          format: uuid
          title: Document Id
          type: string
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      responses:
        '204':
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Delete a library document
      tags:
      - business-library
  /api/v1/businesses/library/images:
    get:
      description: Returns the library images of the authenticated user's business, newest first, paged with `limit` and `offset`.
      operationId: listBusinessLibraryImages
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLibraryImageListResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: List library images
      tags:
      - business-library
    post:
      description: Uploads an image to the library of the authenticated user's business so it can later be attached to messages. The business is taken from the credential; this operation accepts no business parameter.
      operationId: uploadBusinessLibraryImage
      parameters:
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_business_library_image_for_current_business_api_v1_businesses_library_images_post'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLibraryImageOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Upload a library image
      tags:
      - business-library
  /api/v1/businesses/library/images/{image_id}:
    delete:
      description: Removes an image from the library. Messages already sent that referenced it are unaffected.
      operationId: deleteBusinessLibraryImage
      parameters:
      - in: path
        name: image_id
        required: true
        schema:
          format: uuid
          title: Image Id
          type: string
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      responses:
        '204':
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Delete a library image
      tags:
      - business-library
  /api/v1/businesses/library/stickers:
    get:
      description: Returns the library stickers of the authenticated user's business, newest first, paged with `limit` and `offset`.
      operationId: listBusinessLibraryStickers
      parameters:
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: offset
        required: false
        schema:
          default: 0
          minimum: 0
          title: Offset
          type: integer
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLibraryStickerListResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: List library stickers
      tags:
      - business-library
    post:
      description: Uploads a WhatsApp sticker to the library of the authenticated user's business. It must be a 512x512 WebP of at most 100 KB, or 500 KB when animated. Stickers are kept apart from library images and are sent to customers as WhatsApp stickers, without a caption.
      operationId: uploadBusinessLibrarySticker
      parameters:
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_business_library_sticker_for_current_business_api_v1_businesses_library_stickers_post'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessLibraryImageOut'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Upload a library sticker
      tags:
      - business-library
  /api/v1/businesses/library/stickers/{sticker_id}:
    delete:
      description: Removes a sticker from the library. Copies already delivered on WhatsApp are unaffected, but the inbox can no longer show the sticker in earlier messages.
      operationId: deleteBusinessLibrarySticker
      parameters:
      - in: path
        name: sticker_id
        required: true
        schema:
          format: uuid
          title: Sticker Id
          type: string
      - description: Business UUID whose library is targeted. Required when the user has more than one business.
        in: header
        name: business-id
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Business UUID whose library is targeted. Required when the user has more than one business.
          title: Business-Id
      responses:
        '204':
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Missing or invalid credentials.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The credential is valid but not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource, or the business named in the request, does not exist.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected error.
      security:
      - bearerAuth: []
      summary: Delete a library sticker
      tags:
      - business-library
components:
  schemas:
    ApiError:
      description: 'The response body of a handled API error.


        ``detail`` is either a plain string (FastAPI''s default for an

        ``HTTPException`` raised with a string, and for the ``default`` fastapi-users

        messages like ``"Not authenticated"``) or the structured

        :class:`ApiErrorDetail` object described above. ``code`` is present only on

        the top-level shape ``aizap.core.exceptions.AppException`` produces for its

        own 5xx responses (``"INTERNAL_ERROR"`` / ``"DB_ERROR"``); it does not

        duplicate the ``code`` nested inside a structured ``detail``.'
      properties:
        code:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Code
        detail:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/ApiErrorDetail'
          title: Detail
      required:
      - detail
      title: ApiError
      type: object
    ApiErrorDetail:
      additionalProperties: true
      description: 'The structured ``detail`` object some error responses carry.


        Several handlers (the REST API plan gate, the free-tier limits, the

        webhooks entitlement gate, the closed customer-service window) raise

        ``HTTPException(detail={"code": ..., "message": ..., ...})`` — a fixed

        ``code``/``message`` pair plus extra fields specific to that error.

        ``extra="allow"`` keeps those fields in the documented shape instead of

        dropping them.'
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
      - code
      - message
      title: ApiErrorDetail
      type: object
    Body_upload_business_library_image_for_current_business_api_v1_businesses_library_images_post:
      properties:
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        file:
          contentMediaType: application/octet-stream
          title: File
          type: string
        tags:
          anyOf:
          - type: string
          - type: 'null'
          title: Tags
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
      required:
      - file
      title: Body_upload_business_library_image_for_current_business_api_v1_businesses_library_images_post
      type: object
    BusinessLibraryImageOut:
      description: 'Metadata for an image stored in the business library.


        Backed by the :class:`aizap.models.documents.Document` model, filtered to

        image document types.'
      properties:
        business_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Business Id
        content_type:
          title: Content Type
          type: string
        created:
          format: date-time
          title: Created
          type: string
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        document_type:
          title: Document Type
          type: string
        file_size:
          title: File Size
          type: integer
        filename:
          title: Filename
          type: string
        id:
          format: uuid
          title: Id
          type: string
        original_filename:
          title: Original Filename
          type: string
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        uploaded_by_user_id:
          anyOf:
          - format: uuid
            type: string
          - type: 'null'
          title: Uploaded By User Id
        url:
          title: Url
          type: string
      required:
      - id
      - business_id
      - filename
      - original_filename
      - content_type
      - document_type
      - file_size
      - url
      - created
      title: BusinessLibraryImageOut
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    Body_upload_business_library_document_for_current_business_api_v1_businesses_library_documents_post:
      properties:
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        file:
          contentMediaType: application/octet-stream
          title: File
          type: string
        tags:
          anyOf:
          - type: string
          - type: 'null'
          title: Tags
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
      required:
      - file
      title: Body_upload_business_library_document_for_current_business_api_v1_businesses_library_documents_post
      type: object
    Body_upload_business_library_sticker_for_current_business_api_v1_businesses_library_stickers_post:
      properties:
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        file:
          contentMediaType: application/octet-stream
          title: File
          type: string
        tags:
          anyOf:
          - type: string
          - type: 'null'
          title: Tags
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
      required:
      - file
      title: Body_upload_business_library_sticker_for_current_business_api_v1_businesses_library_stickers_post
      type: object
    BusinessLibraryDocumentListResponse:
      description: 'Paginated list of library documents and videos (newest first).


        Same row shape as the image listing — the two differ in which document types they

        carry, not in what is known about one — but a distinct model so the OpenAPI schema

        names the collection for what it holds.'
      properties:
        documents:
          items:
            $ref: '#/components/schemas/BusinessLibraryImageOut'
          title: Documents
          type: array
        has_next:
          title: Has Next
          type: boolean
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        total:
          title: Total
          type: integer
      required:
      - documents
      - total
      - limit
      - offset
      - has_next
      title: BusinessLibraryDocumentListResponse
      type: object
    BusinessLibraryStickerListResponse:
      description: Paginated list of WhatsApp stickers in the library (newest first).
      properties:
        has_next:
          title: Has Next
          type: boolean
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        stickers:
          items:
            $ref: '#/components/schemas/BusinessLibraryImageOut'
          title: Stickers
          type: array
        total:
          title: Total
          type: integer
      required:
      - stickers
      - total
      - limit
      - offset
      - has_next
      title: BusinessLibraryStickerListResponse
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    BusinessLibraryImageListResponse:
      description: Paginated list of library images with stable ordering (newest first).
      properties:
        has_next:
          title: Has Next
          type: boolean
        images:
          items:
            $ref: '#/components/schemas/BusinessLibraryImageOut'
          title: Images
          type: array
        limit:
          title: Limit
          type: integer
        offset:
          title: Offset
          type: integer
        total:
          title: Total
          type: integer
      required:
      - images
      - total
      - limit
      - offset
      - has_next
      title: BusinessLibraryImageListResponse
      type: object
  securitySchemes:
    bearerAuth:
      description: 'Personal access token (izap_pat_…) sent as Authorization: Bearer <token>; dashboard session JWTs are also accepted.'
      scheme: bearer
      type: http