invoiceninja/openapi/paths/products.yaml

  /api/v1/products:
    get:
      tags:
        - products
      summary: "List products"
      description: |
        Lists products, search and filters allow fine grained lists to be generated.    
        Query parameters can be added to perform fine grained filtering of the products list, these are handled by the ProductFilters class
        which defines the methods available
      operationId: getProducts
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - $ref: "#/components/parameters/status"
        - $ref: "#/components/parameters/client_id"
        - $ref: "#/components/parameters/created_at"
        - $ref: "#/components/parameters/updated_at"
        - $ref: "#/components/parameters/is_deleted"
        - $ref: "#/components/parameters/filter_deleted_clients"
        - $ref: "#/components/parameters/vendor_id"
        - name: filter
          in: query
          description: Filter by product name
          required: false
          schema:
            type: string
          example: bob
        - name: product_key
          in: query
          description: Filter by product key
          required: false
          schema:
            type: string
          example: bob
        - name: sort
          in: query
          description: Returns the list sorted by column in ascending or descending order.
          required: false
          schema:
            type: string
          example: id|desc product_key|desc  
      responses:
        200:
          description: "A list of products"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'
    post:
      tags:
        - products
      summary: "Create Product"
      description: "Adds a product to a company"
      operationId: storeProduct
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
      responses:
        200:
          description: "Returns the saved product object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'
  "/api/v1/products/{id}":
    get:
      tags:
        - products
      summary: "Show product"
      description: "Displays a product by id"
      operationId: showProduct
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Product Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the product object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'
    put:
      tags:
        - products
      summary: "Update product"
      description: "Handles the updating of a product by id"
      operationId: updateProduct
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Product Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the Product object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'
    delete:
      tags:
        - products
      summary: "Delete product"
      description: "Handles the deletion of a product by id"
      operationId: deleteProduct
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Product Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns a HTTP status"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'
  "/api/v1/products/{id}/edit":
    get:
      tags:
        - products
      summary: "Edit product"
      description: "Displays an Product by id"
      operationId: editProduct
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
        - name: id
          in: path
          description: "The Product Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      responses:
        200:
          description: "Returns the Product object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'
  "/api/v1/products/create":
    get:
      tags:
        - products
      summary: "Blank product"
      description: "Returns a blank product object with default values"
      operationId: getProductsCreate
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/include"
      responses:
        200:
          description: "A blank Product object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'

  /api/v1/products/bulk:
    post:
      tags:
        - products
      summary: "Bulk product actions"
      description: "Archive / Restore / Delete in bulk"
      operationId: bulkProducts
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/index"
      requestBody:
        description: "Hashed IDs"
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                description: "Array of hashed IDs to be bulk 'actioned"
                type: integer
                example: "[0,1,2,3]"
      responses:
        200:
          description: "The Product response"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'

  "/api/v1/products/{id}/upload":
    put:
      tags:
        - products
      summary: "Add product document"
      description: "Handles the uploading of a document to a product"
      operationId: uploadProduct
      parameters:
        - $ref: "#/components/parameters/X-API-TOKEN"
        - $ref: "#/components/parameters/X-Requested-With"
        - $ref: "#/components/parameters/client_include"
        - name: id
          in: path
          description: "The Product Hashed ID"
          required: true
          schema:
            type: string
            format: string
          example: D2J234DFA
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                _method:
                  type: string
                  example: POST
                documents:
                  type: array
                  format: binary
      responses:
        200:
          description: "Returns the Product object"
          headers:
            X-MINIMUM-CLIENT-VERSION:
              $ref: "#/components/headers/X-MINIMUM-CLIENT-VERSION"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/X-RateLimit-Remaining"
            X-RateLimit-Limit:
              $ref: "#/components/headers/X-RateLimit-Limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        422:
          $ref: '#/components/responses/422'
        default:
          $ref: '#/components/responses/default'