Resourcly Items API

openapi: 3.2.0
info:
  description: API for document processing, item similarity search, and analytics.
  title: Resourcly analytics Items API
  termsOfService: https://resourcly.com/terms
  contact:
    name: API Support
    email: support@resourcly.com
  license:
    name: Proprietary
  version: 1.0.0
servers:
- url: https://api.resourcly.com/v1
tags:
- name: Items
paths:
  /items/{id}/hs-code:
    delete:
      security:
      - BearerAuth: []
      description: Deletes the user's verified/override HS code decision for the item, reverting to AI suggestions.
      tags:
      - Items
      summary: Remove an item's HS code decision
      parameters:
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/{id}/hs-code/override:
    post:
      security:
      - BearerAuth: []
      description: Stores a user-corrected HS code for the item as a durable override that survives AI re-classification. Chapter/heading/subheading are derived from the code.
      tags:
      - Items
      summary: Overwrite an item's HS code
      parameters:
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ItemHSCode'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.HSCodeOverrideRequest'
        description: Corrected HS code + optional description/note
        required: true
  /items/{id}/hs-code/verify:
    post:
      security:
      - BearerAuth: []
      description: Marks an AI-suggested HS code as verified for the item. The decision persists and survives AI re-classification. If no suggestion_id is given, the highest-confidence suggestion is verified.
      tags:
      - Items
      summary: Verify an item's HS code
      parameters:
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ItemHSCode'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.HSCodeVerifyRequest'
        description: Suggestion to verify + optional note
  /items:
    get:
      security:
      - BearerAuth: []
      description: Returns a paginated list of all items the user has access to, ordered by creation date (newest first).
      tags:
      - Items
      summary: List items with pagination
      parameters:
      - description: Max results (default 50, max 100)
        name: limit
        in: query
        schema:
          type: integer
          default: 50
      - description: Pagination offset
        name: offset
        in: query
        schema:
          type: integer
          default: 0
      - description: Comma-separated business node UUIDs to filter by
        name: business_node_ids
        in: query
        schema:
          type: string
      - description: When true (default), return only items with at least one attached file (any type). Pass false to include items with no files.
        name: with_files
        in: query
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.ItemListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/comparison-status/batch:
    post:
      security:
      - BearerAuth: []
      description: Returns review statuses for a batch of item pairs
      tags:
      - Items
      summary: Get comparison review statuses for multiple item pairs
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ComparisonStatusBatchResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.ComparisonStatusBatchRequest'
        description: Item pairs
        required: true
  /items/similarity:
    get:
      security:
      - BearerAuth: []
      description: Returns items that have at least one similarity relationship with a score
      tags:
      - Items
      summary: List items by similarity score range
      parameters:
      - description: Minimum similarity score (inclusive)
        name: min_score
        in: query
        required: true
        schema:
          type: number
      - description: Maximum similarity score (exclusive), 0 for no upper bound
        name: max_score
        in: query
        required: true
        schema:
          type: number
      - description: Max results (default 50, max 100)
        name: limit
        in: query
        schema:
          type: integer
          default: 50
      - description: Pagination offset
        name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.SimilarityItemsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '503':
          description: Neo4j service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/similarity-clusters:
    get:
      security:
      - BearerAuth: []
      description: Returns connected components of items linked by SIMILARITY edges whose
      tags:
      - Items
      summary: List item clusters by AI classification
      parameters:
      - description: AI classification value (e.g. duplicate, alternative)
        name: ai_classification
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handlers.SimilarityClustersResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '503':
          description: Neo4j service not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/similarity-counts:
    get:
      security:
      - BearerAuth: []
      description: Returns for each item ID how many unique other items it has a one-way SIMILARITY relationship to above the given threshold
      tags:
      - Items
      summary: Get similarity out-degree counts for items
      parameters:
      - description: Comma-separated item UUIDs
        name: ids
        in: query
        required: true
        schema:
          type: string
      - description: Minimum similarity score (default 0.70)
        name: threshold
        in: query
        schema:
          type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/{id1}/compare/{id2}:
    get:
      security:
      - BearerAuth: []
      description: Returns a detailed comparison of two items including specifications, similarity scores, and spec differences for side-by-side display
      tags:
      - Items
      summary: Compare two items side-by-side
      parameters:
      - description: First item ID
        name: id1
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - description: Second item ID
        name: id2
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ItemComparisonResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/{id1}/compare/{id2}/ai-analysis:
    get:
      security:
      - BearerAuth: []
      description: 'Returns a cached AI analysis or generates a new one using Claude.

        The analysis includes engineering verdict, side-by-side attribute comparison,

        and catalog management recommendations.'
      tags:
      - Items
      summary: Get AI-powered engineering analysis for two items
      parameters:
      - description: First item ID
        name: id1
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - description: Second item ID
        name: id2
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.AIItemComparisonResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/{id1}/comparison-status/{id2}:
    get:
      security:
      - BearerAuth: []
      description: Returns the review status (duplicate/alternative/rejected/pending) for a pair of items
      tags:
      - Items
      summary: Get comparison review status for two items
      parameters:
      - description: First item ID
        name: id1
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - description: Second item ID
        name: id2
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ComparisonStatusResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
    put:
      security:
      - BearerAuth: []
      description: Sets the review status (duplicate/alternative/rejected) for a pair of items. Pass null status to reset to pending.
      tags:
      - Items
      summary: Update comparison review status for two items
      parameters:
      - description: First item ID
        name: id1
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - description: Second item ID
        name: id2
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ComparisonStatusResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.UpdateComparisonStatusRequest'
        description: Status update
        required: true
  /items/{id}:
    get:
      security:
      - BearerAuth: []
      description: Returns detailed information about an item including specifications, source document, and duplicate group info
      tags:
      - Items
      summary: Get item details
      parameters:
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ItemDetailsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/{id}/source-url:
    get:
      security:
      - BearerAuth: []
      description: Returns a short-lived signed URL to download the item's source document
      tags:
      - Items
      summary: Get signed source document URL for an item
      parameters:
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /items/{id}/visual-similar:
    get:
      security:
      - BearerAuth: []
      description: 'Finds items with visually similar document images using gemini-embedding-2 image embeddings.

        Compares up to 5 images from the item''s source document against all other document images.'
      tags:
      - Items
      summary: Get visually similar items
      parameters:
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - description: Max results (default 20, max 100)
        name: limit
        in: query
        schema:
          type: integer
          default: 20
      - description: Min similarity score 0-1 (default 0.3)
        name: threshold
        in: query
        schema:
          type: number
          default: 0.3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.VisualSimilarResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '503':
          description: Visual search not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
  /v1/items/{id}/preferred:
    put:
      description: Sets or clears the preferred-part flag on an item. The flag is read-only everywhere else and can only be changed here.
      tags:
      - Items
      summary: Mark an item as a preferred part
      parameters:
      - description: Item ID
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ItemDetailsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/models.UpdateItemPreferredRequest'
        description: Preferred flag
        required: true
components:
  schemas:
    handlers.ItemListResponse:
      type: object
      properties:
        business_id:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/services.ItemListEntry'
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
    models.ItemHSCode:
      type: object
      properties:
        chapter:
          description: First 2 digits
          type: string
        confidence_level:
          description: '"high"/"medium"/"low"; empty for override'
          type: string
        confidence_score:
          description: carried over when verified; nil for override
          type: number
        created_at:
          type: string
        decided_at:
          type: string
        decided_by:
          description: user email
          type: string
        heading:
          description: First 4 digits
          type: string
        hs_code:
          description: 6-10 digit HS/HTS code
          type: string
        hs_code_description:
          description: Description of the HS code
          type: string
        id:
          type: string
        item_id:
          type: string
        note:
          description: optional user note (esp. for overrides)
          type: string
        source:
          description: '"verified" or "override"'
          type: string
        source_suggestion_id:
          description: provenance of the verified suggestion
          type: string
        subheading:
          description: First 6 digits
          type: string
        updated_at:
          type: string
    models.SimilarityScores:
      type: object
      properties:
        additional_score:
          description: similarity over the other measurements (0-1)
          type: number
        exact_manufacturer_match:
          description: True if manufacturers match exactly
          type: boolean
        exact_part_number_match:
          description: Flags for exact/tolerance matches
          type: boolean
        fit:
          description: 'Two-stage compare (model_extraction tenant only): a SEPARATE additional score over the

            other part measurements (surface roughness, material, weight, bending radius), computed

            only when the important specs "fit". Deliberately NOT folded into WeightedTotal, so the

            primary score/classification is identical for every tenant.'
          type: boolean
        has_additional:
          description: an additional (other-measurements) score was computed
          type: boolean
        manufacturer_score:
          description: Manufacturer similarity (0-1)
          type: number
        part_number_score:
          description: Part number similarity (0-1)
          type: number
        specifications_score:
          description: Specifications similarity (0-1)
          type: number
        specs_within_tolerance:
          description: True if key specs (mass, dimensions) are within tolerance
          type: boolean
        title_score:
          description: Title semantic similarity (0-1)
          type: number
        weighted_total:
          description: Weighted total score (0-1)
          type: number
    services.SimilarityListItem:
      type: object
      properties:
        business_id:
          type: string
        internal_code:
          description: drawing internal code (Kacher-test); shown as the small identifier line
          type: string
        item_id:
          type: string
        manufacturer:
          type: string
        max_score:
          description: highest SIMILARITY score
          type: number
        part_number:
          type: string
        reviewed_count:
          description: human-validated matches for this item (model_extraction; 0 otherwise)
          type: integer
        similar_count:
          description: number of items above threshold
          type: integer
        title:
          type: string
    models.HSCodeAlternative:
      type: object
      properties:
        code:
          type: string
        description:
          type: string
        reason_rejected:
          type: string
    models.HSCodeOverrideRequest:
      type: object
      properties:
        description:
          type: string
        hs_code:
          type: string
        note:
          type: string
    models.HSCodeVerifyRequest:
      type: object
      properties:
        note:
          type: string
        suggestion_id:
          type: string
    models.ErrorResponse:
      type: object
      properties:
        code:
          type: string
        details: {}
        error:
          type: string
    models.ComparisonStatusResponse:
      type: object
      properties:
        business_id:
          type: string
        created_at:
          type: string
        id:
          type: string
        item_id_1:
          type: string
        item_id_2:
          type: string
        reviewed_at:
          description: When the review was performed
          type: string
        reviewed_by:
          description: Business user ID who reviewed
          type: string
        status:
          description: '"pending", "duplicate", "alternative", "rejected"; with model_extraction also "interchangeable_variant", "superseded", "product_variant", "related_parts", "component_of"'
          type: string
        updated_at:
          type: string
    models.ComparisonStatusBatchResponse:
      type: object
      properties:
        statuses:
          type: array
          items:
            $ref: '#/components/schemas/models.ComparisonStatusResponse'
    models.UpdateItemPreferredRequest:
      type: object
      properties:
        is_preferred:
          type: boolean
    models.AIAnalysisCatalogActions:
      type: object
      properties:
        notes_for_buyer:
          type: string
        primary_part:
          type: string
        secondary_part:
          type: string
        suggested_relationship_tag:
          type: string
    models.DataGovernanceConditionSpec:
      type: object
      properties:
        caseInsensitive:
          type: boolean
        comment:
          type: string
        count:
          type: integer
        countOp:
          type: string
        fieldId:
          type: string
        pattern:
          type: string
    models.AIItemComparisonResponse:
      type: object
      properties:
        analysis:
          description: Present when status == "ready"
          allOf:
          - $ref: '#/components/schemas/models.AIAnalysisResult'
        completion_tokens:
          type: integer
        created_at:
          type: string
        model:
          type: string
        prompt_tokens:
          type: integer
        status:
          description: '"ready", "unavailable"'
          type: string
    handlers.SimilarityItemsResponse:
      type: object
      properties:
        business_id:
          type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/services.SimilarityListItem'
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
    models.ItemPair:
      type: object
      properties:
        item_id_1:
          type: string
        item_id_2:
          type: string
    models.UpdateComparisonStatusRequest:
      type: object
      properties:
        status:
          description: '"duplicate", "alternative", "rejected", or "pending" (resets to null in DB); with model_extraction also "interchangeable_variant", "superseded", "product_variant", "related_parts", "component_of"'
          type: string
    models.DocumentTable:
      type: object
      properties:
        headers:
          description: Table column headers
          type: array
          items:
            type: string
        id:
          description: Table UUID
          type: string
        page_number:
          description: Page number where table was found
          type: integer
        rows:
          description: Table data rows
          type: array
          items:
            type: array
            items:
              type: string
        table_index:
          description: Index of table on the page (0-based)
          type: integer
    models.VisualSimilarItem:
      type: object
      properties:
        classification:
          description: exact_duplicate, duplicate, alternative, different
          type: string
        image_signed_url:
          description: Time-limited signed HTTPS URL
          type: string
        item_id:
          type: string
        manufacturer:
          type: string
        part_number:
          type: string
        similarity_score:
          type: number
        source_filename:
          type: string
        title:
          type: string
    models.DataGovernanceStatementSpec:
      type: object
      properties:
        errorMessage:
          type: string
        expression:
          type: string
        severity:
          type: string
    models.AIAnalysisSimilarityScores:
      type: object
      properties:
        manufacturer_score:
          type: number
        part_number_score:
          type: number
        specifications_score:
          type: number
        system_classification:
          type: string
        system_weighted_total:
          type: number
        title_score:
          type: number
    models.AIAnalysisItemSummary:
      type: object
      properties:
        category:
          type: string
        manufacturer:
          type: string
        part_number:
          type: string
        title:
          type: string
    models.SuggestedCatalogAttribute:
      type: object
      properties:
        aliases:
          description: Alternative names / aliases for this property
          type: array
          items:
            type: string
        property_description:
          description: Human-readable descripti

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