openapi: 3.0.0
info:
  title: API Documentation
  version: 1.0.0
paths:
  /v2/authentications/{entrupy_id}:
    get:
      summary: Get authentication by Entrupy ID
      description: >-
        Returns status, result, certificate, catalog, and image information for
        a specific authentication session.
      tags:
        - Authentication Data
      operationId: get_v2_authentications_entrupy_id
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Default Response (No Optional Data):
                  value:
                    item:
                      entrupy_id: ENTPY12345
                      timestamp:
                        created_at: '2025-05-23T10:00:00Z'
                      status:
                        result:
                          id: authentic
                          final: true
                        initial_result:
                          id: authentic
                          final: false
                        flag: reviewed_ok
                      activity:
                        mode: standard_authentication
                      properties:
                        customer_item_id: SKU9876
                        brand_name: Chanel
                        category_name: Handbag
                      owner:
                        organization_id: ORG_ABC
                        user_id: USER_XYZ
                      certificate:
                        certificate_id: CERT_123
                        url: https://example.com/certificate/ENTPY12345
                      text_fields:
                        notes_to_buyer: Handle with care.
                      images: null
                      catalog: null
                Response with Catalog Only:
                  value:
                    item:
                      entrupy_id: ENTPY12345
                      timestamp:
                        created_at: '2025-05-23T10:00:00Z'
                      status:
                        result:
                          id: authentic
                          final: true
                        initial_result:
                          id: authentic
                          final: false
                        flag: reviewed_ok
                      activity:
                        mode: standard_authentication
                      properties:
                        customer_item_id: SKU9876
                        brand_name: Chanel
                        category_name: Handbag
                      owner:
                        organization_id: ORG_ABC
                        user_id: USER_XYZ
                      certificate:
                        certificate_id: CERT_123
                        url: https://example.com/certificate/ENTPY12345
                      text_fields:
                        notes_to_buyer: Handle with care.
                      images: null
                      catalog:
                        product_information:
                          brand: Chanel
                          category: Shoulder Bag
                          style: Classic Flap Medium
                          material: Lambskin
                          colorway: Black
                          description: >-
                            A timeless Chanel Classic Flap bag in black lambskin
                            with gold-tone hardware.
                        condition_assessment:
                          score: 9
                          rating: Excellent
                          issues:
                            - Faint creasing on exterior
                          details:
                            exterior_condition: Excellent
                            interior_condition: Very Good
                        marketplace_listings:
                          - platform: Fashionphile
                            title: CHANEL Lambskin Quilted Medium Double Flap Black
                            price: $7,500.00
                            currency: USD
                            link: >-
                              https://www.fashionphile.com/p/chanel-lambskin-quilted-medium-double-flap-black-123456
                            confidence: 0.92
                Response with Images Only:
                  value:
                    item:
                      entrupy_id: ENTPY12345
                      timestamp:
                        created_at: '2025-05-23T10:00:00Z'
                      status:
                        result:
                          id: authentic
                          final: true
                        initial_result:
                          id: authentic
                          final: false
                        flag: reviewed_ok
                      activity:
                        mode: standard_authentication
                      properties:
                        customer_item_id: SKU9876
                        brand_name: Chanel
                        category_name: Handbag
                      owner:
                        organization_id: ORG_ABC
                        user_id: USER_XYZ
                      certificate:
                        certificate_id: CERT_123
                        url: https://example.com/certificate/ENTPY12345
                      text_fields:
                        notes_to_buyer: Handle with care.
                      images:
                        - type: thumbnail
                          url: https://example.com/img/ENTPY12345_thumb1.jpg
                        - type: high_resolution
                          url: https://example.com/img/ENTPY12345_hr1.jpg
                      catalog: null
                Response with Catalog and Images:
                  value:
                    item:
                      entrupy_id: ENTPY12345
                      timestamp:
                        created_at: '2025-05-23T10:00:00Z'
                      status:
                        result:
                          id: authentic
                          final: true
                        initial_result:
                          id: authentic
                          final: false
                        flag: reviewed_ok
                      activity:
                        mode: standard_authentication
                      properties:
                        customer_item_id: SKU9876
                        brand_name: Chanel
                        category_name: Handbag
                      owner:
                        organization_id: ORG_ABC
                        user_id: USER_XYZ
                      certificate:
                        certificate_id: CERT_123
                        url: https://example.com/certificate/ENTPY12345
                      text_fields:
                        notes_to_buyer: Handle with care.
                      images:
                        - type: thumbnail
                          url: https://example.com/img/ENTPY12345_thumb1.jpg
                        - type: high_resolution
                          url: https://example.com/img/ENTPY12345_hr1.jpg
                      catalog:
                        product_information:
                          brand: Chanel
                          category: Shoulder Bag
                          style: Classic Flap Medium
                          material: Lambskin
                          colorway: Black
                          description: >-
                            A timeless Chanel Classic Flap bag in black lambskin
                            with gold-tone hardware.
                        condition_assessment:
                          score: 9
                          rating: Excellent
                          issues:
                            - Faint creasing on exterior
                          details:
                            exterior_condition: Excellent
                            interior_condition: Very Good
                        marketplace_listings:
                          - platform: Fashionphile
                            title: CHANEL Lambskin Quilted Medium Double Flap Black
                            price: $7,500.00
                            currency: USD
                            link: >-
                              https://www.fashionphile.com/p/chanel-lambskin-quilted-medium-double-flap-black-123456
                            confidence: 0.92
        '404':
          description: Response for status 404
          content:
            application/json:
              examples:
                Authentication Not Found:
                  value:
                    error_code: NOT_FOUND
                    message: Authentication with entrupy_id ENTPY_NOT_FOUND not found.
      parameters:
        - name: entrupy_id
          in: path
          required: true
          schema:
            type: string
  /v2/authentications/{entrupy_id}/flag:
    post:
      summary: Flag an authentication
      description: Submits a flag for an authentication result.
      tags:
        - Authentication Actions
      operationId: post_v2_authentications_entrupy_id_flag
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Flag Acknowledged:
                  value:
                    entrupy_id: ENTPYFLAG123
                    flag_status: pending_review
                    message: >-
                      Flag submitted successfully for Entrupy ID: ENTPYFLAG123.
                      Reason: Suspected counterfeit based on stitching pattern.
        '400':
          description: Response for status 400
          content:
            application/json:
              examples:
                Bad Request (e.g., Missing Reason):
                  value:
                    error_code: BAD_REQUEST
                    message: 'Invalid request: ''reason'' field is required.'
        '404':
          description: Response for status 404
          content:
            application/json:
              examples:
                Authentication Not Found:
                  value:
                    error_code: NOT_FOUND
                    message: >-
                      Authentication with entrupy_id FLAG_NOT_FOUND not found
                      and cannot be flagged.
      parameters:
        - name: entrupy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlagRequest'
            examples:
              Standard Flag Submission:
                value:
                  reason: Suspected counterfeit based on stitching pattern.
                  comments: Compared with retail version, stitching is inconsistent.
  /v2/authentications/{entrupy_id}/transfer:
    post:
      summary: Initiate B2B non-verified certificate transfer
      description: Initiates a B2B non-verified transfer of an Entrupy certificate.
      tags:
        - Authentication Actions
      operationId: post_v2_authentications_entrupy_id_transfer
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Transfer Initiated:
                  value:
                    entrupy_id: ENTPYTRANSFER456
                    transfer_status: initiated
                    new_holder_information: Transfer initiated to PARTNER_PLATFORM_ID_789.
                    message: Certificate transfer initiated for ENTPYTRANSFER456.
        '400':
          description: Response for status 400
          content:
            application/json:
              examples:
                Bad Request (e.g., Missing Platform ID):
                  value:
                    error_code: BAD_REQUEST
                    message: >-
                      Invalid request: 'recipient_platform_id' is required for
                      transfer.
        '404':
          description: Response for status 404
          content:
            application/json:
              examples:
                Authentication Not Found:
                  value:
                    error_code: NOT_FOUND
                    message: >-
                      Authentication with entrupy_id TRANSFER_NOT_FOUND not
                      found and cannot be transferred.
      parameters:
        - name: entrupy_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferRequest'
            examples:
              Basic B2B Transfer:
                value:
                  recipient_platform_id: PARTNER_PLATFORM_ID_789
                  recipient_user_email: null
                  notes: Standard B2B transfer of ownership.
              Transfer with Recipient Email:
                value:
                  recipient_platform_id: MARKETPLACE_XYZ
                  recipient_user_email: buyer_email@example.com
                  notes: Transferring to end-user on marketplace platform.
  /v2/fingerprints/{entrupy_id}:
    get:
      summary: Get fingerprint by Entrupy ID
      description: >-
        Return the fingerprint record for an item. Use this endpoint when
        verifying that a new submission matches the original fingerprint stored
        by Entrupy.
      tags:
        - Fingerprint Data
      operationId: get_v2_fingerprints_entrupy_id
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Successful Fingerprint Response:
                  value:
                    item:
                      entrupy_id: ENTPYFP123
                      timestamp:
                        created_at: '2023-10-26T10:00:00Z'
                        last_updated_at: '2023-10-26T10:05:00Z'
                      status:
                        result:
                          id: verified
                          final: true
                        initial_result: null
                        flag: null
                      activity:
                        mode: fingerprint_registration
                      properties:
                        customer_item_id: CUST_FP_ITEM_789
                        device_id: DEVICE_ABC
                        app_version: 1.5.0
                      owner:
                        organization_id: ORG_XYZ
                        user_id: USER_123
                      certificate: null
                      text_fields:
                        internal_notes: Fingerprint captured for archival.
                        location_captured: Warehouse A
                      images:
                        microscopic_close_up:
                          url: https://example.com/fp/ENTPYFP123_mc1.jpg
                          metadata:
                            zoom_level: 100x
                        overview_image:
                          url: https://example.com/fp/ENTPYFP123_ov1.jpg
                      fingerprint_parent:
                        entrupy_id: ENTPYAUTHPARENT456
                        relationship_type: derived_from_authentication
        '404':
          description: Response for status 404
          content:
            application/json:
              examples:
                Fingerprint Not Found:
                  value:
                    error_code: NOT_FOUND
                    message: >-
                      Fingerprint with entrupy_id FINGERPRINT_NOT_FOUND not
                      found.
      parameters:
        - name: entrupy_id
          in: path
          required: true
          schema:
            type: string
  /v2/lookup/authentications/{lookup_value}:
    get:
      summary: Lookup authentication by Customer ID
      description: >-
        Retrieve the latest authentication for an item using your own
        `customer_item_id`. This helps correlate Entrupy results with records in
        your inventory system.
      tags:
        - Authentication Data
      operationId: get_v2_lookup_authentications_lookup_value
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Successful Lookup Response:
                  value:
                    item:
                      entrupy_id: ENTPYLKUP789
                      timestamp:
                        created_at: '2023-11-15T14:30:00Z'
                        last_updated_at: '2023-11-15T14:35:00Z'
                      status:
                        result:
                          id: authentic
                          final: true
                        initial_result:
                          id: authentic
                          final: false
                        flag: null
                      activity:
                        mode: standard_authentication
                      properties:
                        customer_item_id: CUST_LOOKUP_001
                        brand: Louis Vuitton
                        category: Handbag
                      owner:
                        organization_id: ORG_ABC
                        user_id: USER_456
                      certificate:
                        certificate_id: CERT_LKUP_101
                        url: https://example.com/certificate/ENTPYLKUP789
                      text_fields:
                        notes_for_certificate: Purchased from trusted reseller.
                      images:
                        main_image:
                          url: https://example.com/auth/ENTPYLKUP789_main.jpg
                        close_up_logo:
                          url: https://example.com/auth/ENTPYLKUP789_logo_cu.jpg
                      fingerprint_parent: null
        '404':
          description: Response for status 404
          content:
            application/json:
              examples:
                Authentication Not Found by Lookup:
                  value:
                    error_code: NOT_FOUND
                    message: >-
                      Authentication with lookup_value CUST_NOT_FOUND_XYZ not
                      found.
      parameters:
        - name: lookup_value
          in: path
          required: true
          schema:
            type: string
  /v2/search/authentications:
    post:
      summary: Search authentications
      description: >-
        Search your organization's authentication history using flexible
        filters. This endpoint powers dashboards and reporting without requiring
        you to store all results locally.
      tags:
        - Authentication Data
      operationId: post_v2_search_authentications
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Successful Search with Results:
                  value:
                    items:
                      - entrupy_id: ENTPYSRCH001
                        timestamp:
                          created_at: '2023-11-20T10:00:00Z'
                        status:
                          result:
                            id: authentic
                            final: true
                          initial_result: null
                          flag: null
                        activity:
                          mode: standard_authentication
                        properties:
                          customer_item_id: CUST_SEARCH_A001
                          brand: Chanel
                        owner: null
                        certificate:
                          url: https://example.com/certificate/ENTPYSRCH001
                        text_fields: null
                        images: null
                        fingerprint_parent: null
                      - entrupy_id: ENTPYSRCH002
                        timestamp:
                          created_at: '2023-10-05T15:30:00Z'
                        status:
                          result:
                            id: authentic
                            final: true
                          initial_result: null
                          flag: null
                        activity:
                          mode: data_entry_authentication
                        properties:
                          customer_item_id: CUST_SEARCH_B005
                          brand: Gucci
                        owner: null
                        certificate: null
                        text_fields:
                          notes: From Fall 2023 collection
                        images: null
                        fingerprint_parent: null
                    item_count: 2
                    next_cursor: CURSOR_FOR_NEXT_PAGE_ABC456
                Successful Search with No Results:
                  value:
                    items: []
                    item_count: 0
                    next_cursor: null
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              Simple Search by Customer Item ID:
                value:
                  limit: 10
                  filters:
                    - key: text_fields.customer_item_id
                      value: CUST_SEARCH_A001
                      values: null
                      exclude: false
                      text_fields: null
                  format_options: null
              Complex Search with Multiple Filters and Pagination:
                value:
                  limit: 25
                  filters:
                    - key: properties.brand.id
                      value: louis_vuitton
                      values: null
                      exclude: false
                      text_fields: null
                    - key: status.result.id
                      value: authentic
                      values: null
                      exclude: false
                      text_fields: null
                    - key: activity.mode
                      value: null
                      values:
                        - standard_authentication
                        - data_entry_authentication
                      exclude: false
                      text_fields: null
                  format_options: null
                  sort_by: timestamp.created_at
                  sort_order: descending
                  cursor: CURSOR_PREVIOUS_SEARCH_XYZ123
  /v2/search/fingerprints:
    post:
      summary: Search fingerprints
      description: >-
        Search fingerprint records to track items that have been registered for
        identity verification. Filters let you narrow results to specific users
        or metadata.
      tags:
        - Fingerprint Data
      operationId: post_v2_search_fingerprints
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Successful Fingerprint Search with Results:
                  value:
                    items:
                      - entrupy_id: ENTPYFP456
                        timestamp:
                          created_at: '2023-12-01T10:00:00Z'
                          last_updated_at: '2023-12-01T10:05:00Z'
                        status:
                          result:
                            id: verified
                            final: true
                          initial_result: null
                          flag: null
                        activity:
                          mode: fingerprint_registration
                        properties:
                          customer_item_id: FP_ITEM_001
                          brand:
                            id: some_brand_id
                            name: Example Brand
                          device_id: DEVICE_XYZ
                          app_version: 1.6.0
                        owner:
                          organization_id: ORG_123
                          user_id: USER_ABC
                        certificate: null
                        text_fields:
                          internal_notes: Archival fingerprint.
                        images:
                          microscopic_close_up:
                            url: https://example.com/fp/ENTPYFP456_mc1.jpg
                          overview_image:
                            url: https://example.com/fp/ENTPYFP456_ov1.jpg
                        fingerprint_parent: null
                    item_count: 1
                    next_cursor: CURSOR_FOR_NEXT_PAGE_FP
                Successful Fingerprint Search with No Results:
                  value:
                    items: []
                    item_count: 0
                    next_cursor: null
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              Simple Fingerprint Search:
                value:
                  limit: 5
                  filters:
                    - key: properties.brand.id
                      value: some_brand_id
                      values: null
                      exclude: false
                      text_fields: null
                    - key: text_fields.customer_item_id
                      value: FP_ITEM_001
                      values: null
                      exclude: false
                      text_fields: canonical
                  format_options: null
  /v2/config/authentications:
    post:
      summary: Authentication config
      description: >-
        Return brand and material options your token can access. Use this data
        to populate capture forms in your app and ensure requests use valid
        values.
      tags:
        - Integrations
      operationId: post_v2_config_authentications
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Successful Config Response:
                  value:
                    config:
                      brands:
                        - brand_id: louis_vuitton
                          display:
                            name: Louis Vuitton
                          materials:
                            - material_id: monogram_canvas
                              display:
                                name: Monogram Canvas
                              details:
                                - field_alias: identifier
                                  display:
                                    name: Date Code
                            - material_id: damier_ebene
                              display:
                                name: Damier Ebene
                              details:
                                - field_alias: identifier
                                  display:
                                    name: Date Code
                        - brand_id: chanel
                          display:
                            name: Chanel
                          materials:
                            - material_id: caviar_leather
                              display:
                                name: Caviar Leather
                              details:
                                - field_alias: identifier
                                  display:
                                    name: Serial Number
                    iat: 1678886400
                    exp: 1678972800
      parameters: []
  /v2/integrations/app-login-voucher:
    post:
      summary: Create login voucher
      description: >-
        Generate an encrypted login voucher for the mobile app. This legacy flow
        allows a user to sign in to Entrupy before the `authorize-user` method
        was introduced.
      tags:
        - Integrations
      operationId: post_v2_integrations_app-login-voucher
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Successful Creation:
                  value:
                    login_voucher: <encrypted_voucher_string>
                    username: YourOrg-testuser123
        '400':
          description: Response for status 400
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    error_code: BAD_REQUEST
                    message: 'Missing some of required keys: unique_user_id and email'
        '409':
          description: Response for status 409
          content:
            application/json:
              examples:
                Conflict - User Exists:
                  value:
                    error_code: CONFLICT
                    message: User already exists with conflicting information.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppLoginVoucherRequest'
            examples:
              Standard Request:
                value:
                  unique_user_id: testuser123
                  email: testuser123@example.com
                  first_name: Test
                  last_name: User
  /v2/integrations/authorize-user:
    post:
      summary: Authorize user
      description: >-
        Sign an authorization request from your mobile client so the SDK can
        obtain a session token from Entrupy. This is the preferred workflow for
        new integrations.
      tags:
        - Integrations
      operationId: post_v2_integrations_authorize-user
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                Successful Authorization:
                  value:
                    signed_authorization_request: <signed_sdk_authorization_request_payload>
                    username: YourOrg-test-sdk-user-789
        '400':
          description: Response for status 400
          content:
            application/json:
              examples:
                Bad Request:
                  value:
                    error_code: BAD_REQUEST
                    message: >-
                      Missing some of required keys: unique_user_id and email
                      and sdk_authorization_request
        '403':
          description: Response for status 403
          content:
            application/json:
              examples:
                Forbidden:
                  value:
                    error_code: FORBIDDEN
                    message: Not authorized for generating auth tokens.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthorizeUserRequest'
            examples:
              Standard Request:
                value:
                  unique_user_id: test-sdk-user-789
                  email: test-sdk-user-789@example.com
                  sdk_authorization_request: >-
                    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
                  first_name: SDKTest
                  last_name: User
  /v2/search/domains:
    post:
      summary: Search registered domains
      description: >-
        List domain names that have been verified for use with webhook
        callbacks. Webhooks can only target these domains.
      tags:
        - Webhooks
      operationId: post_v2_search_domains
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                default:
                  value:
                    items:
                      - create_timestamp: null
                        domain_name: sample-endpoint.entrupy.com
                        domain_owner: null
                        domain_uuid: b9b39947-8a16-483d-a7eb-2b961c41b2f7
                    item_count: 1
                    next_cursor: null
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaginationRequest'
            examples:
              default:
                value:
                  limit: 10
                  cursor: null
  /v2/webhooks:
    post:
      summary: Create webhook
      description: >-
        Register a webhook endpoint to receive real-time notifications such as
        session completion or support messages. The target URL must be on a
        registered domain and payloads are signed with your secret key.
      tags:
        - Webhooks
      operationId: post_v2_webhooks
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                default:
                  value:
                    channel: default
                    create_timestamp: null
                    endpoint:
                      type: url
                      value: https://sample-endpoint.entrupy.com/notifications
                    filters:
                      - key: activity.name
                        value: authentication
                    webhook_owner: null
                    webhook_uuid: cff3fe0e-122a-4cb6-8b73-465c529d8b02
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
            examples:
              default:
                value:
                  endpoint:
                    type: url
                    value: https://sample-endpoint.entrupy.com/notifications
                  secret_key: ExampleSecretKey1234567890
                  channel: null
                  filters:
                    - key: activity.name
                      value: authentication
  /v2/search/webhooks:
    post:
      summary: Search webhooks
      description: >-
        List active webhook configurations owned by your organization. Use this
        to audit or manage existing callback endpoints.
      tags:
        - Webhooks
      operationId: post_v2_search_webhooks
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                default:
                  value:
                    items:
                      - channel: default
                        create_timestamp: null
                        endpoint:
                          type: url
                          value: https://sample-endpoint.entrupy.com/notifications
                        filters:
                          - key: activity.name
                            value: authentication
                        webhook_owner: null
                        webhook_uuid: cff3fe0e-122a-4cb6-8b73-465c529d8b02
                    item_count: 1
                    next_cursor: null
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaginationRequest'
            examples:
              default:
                value:
                  limit: 10
                  cursor: null
  /v2/webhooks/{webhook_uuid}:
    get:
      summary: Get webhook
      description: >-
        Retrieve details about a specific webhook, including its filters,
        channel, and current delivery status.
      tags:
        - Webhooks
      operationId: get_v2_webhooks_webhook_uuid
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                default:
                  value:
                    channel: default
                    create_timestamp: null
                    endpoint:
                      type: url
                      value: https://sample-endpoint.entrupy.com/notifications
                    filters:
                      - key: activity.name
                        value: authentication
                    webhook_owner: null
                    webhook_uuid: cff3fe0e-122a-4cb6-8b73-465c529d8b02
      parameters:
        - name: webhook_uuid
          in: path
          required: true
          schema:
            type: string
  /v2/webhooks/{webhook_uuid}/deactivate:
    post:
      summary: Deactivate webhook
      description: >-
        Disable a webhook so that no further events are delivered. The webhook
        remains in the system and can be reactivated or inspected later.
      tags:
        - Webhooks
      operationId: post_v2_webhooks_webhook_uuid_deactivate
      deprecated: false
      responses:
        '200':
          description: Response for status 200
          content:
            application/json:
              examples:
                default:
                  value:
                    status: ok
      parameters:
        - name: webhook_uuid
          in: path
          required: true
          schema:
            type: string
components:
  schemas:
    GetAuthenticationV2Params:
      properties:
        include_catalog:
          anyOf:
            - type: boolean
            - type: 'null'
          default: false
          description: Set to true to include the 'catalog' object in the response.
          title: Include Catalog
        include_images:
          anyOf:
            - type: boolean
            - type: 'null'
          default: false
          description: Set to true to include the 'images' data in the response.
          title: Include Images
      title: GetAuthenticationV2Params
      type: object
    CatalogConditionAssessmentModel:
      properties:
        score:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          example: 8.5
          title: Score
        rating:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Very Good
          title: Rating
        issues:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          example:
            - Minor corner wear
            - Light handle darkening
          title: Issues
        details:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          example:
            exterior: Good
            interior: Excellent
          title: Details
      title: CatalogConditionAssessmentModel
      type: object
    CatalogDataModel:
      properties:
        product_information:
          anyOf:
            - $ref: '#/components/schemas/CatalogProductInformationModel'
            - type: 'null'
          default: null
        condition_assessment:
          anyOf:
            - $ref: '#/components/schemas/CatalogConditionAssessmentModel'
            - type: 'null'
          default: null
        marketplace_listings:
          anyOf:
            - items:
                $ref: '#/components/schemas/CatalogMarketplaceListingModel'
              type: array
            - type: 'null'
          default: null
          title: Marketplace Listings
      title: CatalogDataModel
      type: object
    CatalogMarketplaceListingModel:
      properties:
        platform:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: The RealReal
          title: Platform
        title:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Louis Vuitton Neverfull MM Monogram
          title: Title
        price:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: $1,200.00
          title: Price
        currency:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: USD
          title: Currency
        link:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: >-
            https://www.therealreal.com/products/women/handbags/totes/louis-vuitton-monogram-neverfull-mm-w-pouch-h6g0h
          title: Link
        confidence:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          example: 0.95
          title: Confidence
      title: CatalogMarketplaceListingModel
      type: object
    CatalogProductInformationModel:
      properties:
        brand:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Louis Vuitton
          title: Brand
        category:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Tote Bag
          title: Category
        style:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Neverfull MM
          title: Style
        material:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Monogram Canvas
          title: Material
        colorway:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Beige/Brown
          title: Colorway
        description:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Iconic Louis Vuitton tote in classic monogram canvas.
          title: Description
      title: CatalogProductInformationModel
      type: object
    V2ActivityModel:
      properties:
        mode:
          title: Mode
          type: string
      required:
        - mode
      title: V2ActivityModel
      type: object
    V2ImageDetail:
      properties:
        type:
          example: thumbnail
          title: Type
          type: string
        url:
          example: https://example.com/image_thumb.jpg
          title: Url
          type: string
      required:
        - type
        - url
      title: V2ImageDetail
      type: object
    V2ItemModel:
      additionalProperties: true
      properties:
        entrupy_id:
          example: ENTPY12345
          title: Entrupy Id
          type: string
        timestamp:
          example:
            created_at: '2025-05-23T10:00:00Z'
          title: Timestamp
          type: object
        status:
          $ref: '#/components/schemas/V2StatusModel'
        activity:
          $ref: '#/components/schemas/V2ActivityModel'
        properties:
          type: object
          example:
            customer_item_id: SKU9876
          title: Properties
        owner:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Owner
        certificate:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Certificate
        text_fields:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Text Fields
        images:
          anyOf:
            - items:
                $ref: '#/components/schemas/V2ImageDetail'
              type: array
            - type: 'null'
          default: null
          title: Images
        catalog:
          anyOf:
            - $ref: '#/components/schemas/CatalogDataModel'
            - type: 'null'
          default: null
      required:
        - entrupy_id
        - timestamp
        - status
        - activity
        - properties
      title: V2ItemModel
      type: object
    V2ResultModel:
      properties:
        id:
          title: Id
          type: string
        final:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Final
      required:
        - id
      title: V2ResultModel
      type: object
    V2StatusModel:
      properties:
        result:
          $ref: '#/components/schemas/V2ResultModel'
        initial_result:
          anyOf:
            - $ref: '#/components/schemas/V2ResultModel'
            - type: 'null'
          default: null
        flag:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Flag
      required:
        - result
      title: V2StatusModel
      type: object
    V2ItemResponse:
      additionalProperties: true
      properties:
        item:
          $ref: '#/components/schemas/V2ItemModel'
      required:
        - item
      title: V2ItemResponse
      type: object
    ErrorResponse:
      properties:
        error_code:
          title: Error Code
          type: string
        message:
          title: Message
          type: string
      required:
        - error_code
        - message
      title: ErrorResponse
      type: object
    FlagRequest:
      properties:
        reason:
          example: Incorrect result.
          title: Reason
          type: string
        comments:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: I believe the item is authentic.
          title: Comments
      required:
        - reason
      title: FlagRequest
      type: object
    FlagResponse:
      properties:
        entrupy_id:
          example: ENTPY12345
          title: Entrupy Id
          type: string
        flag_status:
          example: pending_review
          title: Flag Status
          type: string
        message:
          example: 'Flag submitted successfully. Entrupy ID: ENTPY12345'
          title: Message
          type: string
      required:
        - entrupy_id
        - flag_status
        - message
      title: FlagResponse
      type: object
    TransferRequest:
      properties:
        recipient_platform_id:
          example: PLATFORM_XYZ
          title: Recipient Platform Id
          type: string
        recipient_user_email:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: buyer@example.com
          title: Recipient User Email
        notes:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Transferring ownership post-sale.
          title: Notes
      required:
        - recipient_platform_id
      title: TransferRequest
      type: object
    TransferResponse:
      properties:
        entrupy_id:
          example: ENTPY12345
          title: Entrupy Id
          type: string
        transfer_status:
          example: initiated
          title: Transfer Status
          type: string
        new_holder_information:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          example: Transferred to PLATFORM_XYZ
          title: New Holder Information
        message:
          example: Certificate transfer initiated for ENTPY12345.
          title: Message
          type: string
      required:
        - entrupy_id
        - transfer_status
        - message
      title: TransferResponse
      type: object
    ActivityModel:
      properties:
        mode:
          title: Mode
          type: string
      required:
        - mode
      title: ActivityModel
      type: object
    ItemModel:
      additionalProperties: true
      properties:
        entrupy_id:
          title: Entrupy Id
          type: string
        timestamp:
          title: Timestamp
          type: object
        status:
          $ref: '#/components/schemas/StatusModel'
        activity:
          $ref: '#/components/schemas/ActivityModel'
        properties:
          type: object
          title: Properties
        owner:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Owner
        certificate:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Certificate
        text_fields:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Text Fields
        images:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Images
        fingerprint_parent:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Fingerprint Parent
      required:
        - entrupy_id
        - timestamp
        - status
        - activity
        - properties
      title: ItemModel
      type: object
    ResultModel:
      properties:
        id:
          title: Id
          type: string
        final:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Final
      required:
        - id
      title: ResultModel
      type: object
    StatusModel:
      properties:
        result:
          $ref: '#/components/schemas/ResultModel'
        initial_result:
          anyOf:
            - $ref: '#/components/schemas/ResultModel'
            - type: 'null'
          default: null
        flag:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Flag
      required:
        - result
      title: StatusModel
      type: object
    ItemResponse:
      additionalProperties: true
      properties:
        item:
          $ref: '#/components/schemas/ItemModel'
      required:
        - item
      title: ItemResponse
      type: object
    SearchFilter:
      additionalProperties: true
      properties:
        key:
          $ref: '#/components/schemas/SearchFilterKey'
          description: >-
            Filter key. Allowed values are defined in the ``SearchFilterKey``
            enum.
        value:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: Match a single value. Provide either ``value`` or ``values``.
          title: Value
        values:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          description: >-
            Match any of the provided values. Provide either ``value`` or
            ``values``.
          title: Values
        exclude:
          anyOf:
            - type: boolean
            - type: 'null'
          default: false
          description: If true, exclude items matching this filter.
          title: Exclude
        text_fields:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: 'Lookup mode for text fields: ''canonical'' or ''verbatim''.'
          title: Text Fields
      required:
        - key
      title: SearchFilter
      type: object
    SearchFilterKey:
      description: Supported filter keys for search endpoints.
      enum:
        - activity.form_factor
        - activity.mode
        - owner.organization.name
        - owner.user.username
        - properties.brand.id
        - properties.material.id
        - status.flag
        - status.result.id
        - text_fields.customer_item_id
        - text_fields.identifier
        - text_fields.style_code
        - text_fields.us_size
        - fingerprint_parent.entrupy_id
        - fingerprint_parent.customer_item_id
      title: SearchFilterKey
      type: string
    SearchRequest:
      additionalProperties: true
      properties:
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          default: 10
          description: Maximum number of results to return (max 25).
          title: Limit
        filters:
          anyOf:
            - items:
                $ref: '#/components/schemas/SearchFilter'
              type: array
            - type: 'null'
          default: null
          description: List of filters to apply to the search results.
          title: Filters
        format_options:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          description: Advanced formatting options for results.
          title: Format Options
      title: SearchRequest
      type: object
    SearchResponse:
      additionalProperties: true
      description: Response model for search endpoints.
      properties:
        items:
          anyOf:
            - items:
                $ref: '#/components/schemas/ItemModel'
              type: array
            - type: 'null'
          default: null
          title: Items
        item_count:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          title: Item Count
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Next Cursor
      title: SearchResponse
      type: object
    ConfigResponse:
      additionalProperties: true
      description: Response model for authentication config.
      properties:
        config:
          title: Config
          type: object
        iat:
          title: Iat
        exp:
          title: Exp
      required:
        - config
        - iat
        - exp
      title: ConfigResponse
      type: object
    AppLoginVoucherRequest:
      additionalProperties: true
      description: Request body for creating an app login voucher.
      properties:
        unique_user_id:
          description: A unique identifier for the user within your system.
          example: user123
          title: Unique User Id
          type: string
        email:
          description: The user's email address.
          example: user@example.com
          title: Email
          type: string
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The user's first name.
          example: John
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The user's last name.
          example: Doe
          title: Last Name
      required:
        - unique_user_id
        - email
      title: AppLoginVoucherRequest
      type: object
    LoginVoucherResponse:
      description: Response for login voucher generation.
      properties:
        login_voucher:
          title: Login Voucher
          type: string
        username:
          title: Username
          type: string
      required:
        - login_voucher
        - username
      title: LoginVoucherResponse
      type: object
    AuthorizeUserRequest:
      additionalProperties: true
      description: Request body for authorizing a user via SDK request.
      properties:
        unique_user_id:
          description: A unique identifier for the user within your system.
          example: user456
          title: Unique User Id
          type: string
        email:
          description: The user's email address.
          example: another_user@example.com
          title: Email
          type: string
        sdk_authorization_request:
          description: The authorization request string generated by the Entrupy SDK.
          example: <base64_encoded_sdk_payload>
          title: Sdk Authorization Request
          type: string
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The user's first name.
          example: Jane
          title: First Name
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The user's last name.
          example: Smith
          title: Last Name
      required:
        - unique_user_id
        - email
        - sdk_authorization_request
      title: AuthorizeUserRequest
      type: object
    AuthorizeUserResponse:
      description: Response for authorize user request.
      properties:
        signed_authorization_request:
          title: Signed Authorization Request
          type: string
        username:
          title: Username
          type: string
      required:
        - signed_authorization_request
        - username
      title: AuthorizeUserResponse
      type: object
    PaginationRequest:
      additionalProperties: true
      description: Simple request model for limit/cursor pagination.
      properties:
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          default: 25
          title: Limit
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Cursor
      title: PaginationRequest
      type: object
    DomainModel:
      additionalProperties: true
      description: Model representing a registered domain.
      properties:
        create_timestamp:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Create Timestamp
        domain_name:
          title: Domain Name
          type: string
        domain_owner:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Domain Owner
        domain_uuid:
          title: Domain Uuid
          type: string
      required:
        - domain_name
        - domain_uuid
      title: DomainModel
      type: object
    DomainSearchResponse:
      additionalProperties: true
      description: Response for domain search endpoint.
      properties:
        items:
          anyOf:
            - items:
                $ref: '#/components/schemas/DomainModel'
              type: array
            - type: 'null'
          default: null
          title: Items
        item_count:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          title: Item Count
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Next Cursor
      title: DomainSearchResponse
      type: object
    WebhookCreateRequest:
      additionalProperties: true
      description: Request body for creating a webhook.
      properties:
        endpoint:
          title: Endpoint
          type: object
        secret_key:
          title: Secret Key
          type: string
        channel:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Channel
        filters:
          anyOf:
            - items:
                type: object
              type: array
            - type: 'null'
          default: null
          title: Filters
      required:
        - endpoint
        - secret_key
      title: WebhookCreateRequest
      type: object
    WebhookModel:
      additionalProperties: true
      description: Model representing a webhook.
      properties:
        channel:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Channel
        create_timestamp:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Create Timestamp
        endpoint:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Endpoint
        filters:
          anyOf:
            - items:
                type: object
              type: array
            - type: 'null'
          default: null
          title: Filters
        webhook_owner:
          anyOf:
            - type: object
            - type: 'null'
          default: null
          title: Webhook Owner
        webhook_uuid:
          title: Webhook Uuid
          type: string
      required:
        - webhook_uuid
      title: WebhookModel
      type: object
    WebhookSearchResponse:
      additionalProperties: true
      description: Response for webhook search endpoint.
      properties:
        items:
          anyOf:
            - items:
                $ref: '#/components/schemas/WebhookModel'
              type: array
            - type: 'null'
          default: null
          title: Items
        item_count:
          anyOf:
            - type: integer
            - type: 'null'
          default: null
          title: Item Count
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Next Cursor
      title: WebhookSearchResponse
      type: object
    StatusResponse:
      description: Simple health/status response.
      properties:
        status:
          example: ok
          title: Status
          type: string
      required:
        - status
      title: StatusResponse
      type: object
