VSCO Products API

openapi: 3.0.0
info:
  title: VSCO Workspace Brands Products API
  termsOfService: https://terms-of-service.vsco.page/
  description: This API is for interacting with a single Studio using <a href="https://workspace.vsco.co/settings/api" target="_blank">an API Key</a>.
  contact:
    name: VSCO Workspace Support
    url: https://help.workspace.vsco.co/
    email: workspace-support@vsco.co
  version: v2.0.0
  x-logo:
    url: https://workspace.vsco.co/static/Images/Public/Logo.Black.vsco.svg
    altText: VSCO Workspace
servers:
- url: https://tave.io/v2
  description: Legacy Táve API production environment
- url: https://workspace.vsco.co/api/v2
  description: Workspace API production environment
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Products
paths:
  /product:
    get:
      summary: Get a list of products
      operationId: listResourceProduct
      x-entity: Product
      parameters:
      - name: sortBy
        in: query
        description: Sort items in the collection by the given property.
        schema:
          title: Sort objects by properties
          type: string
          anyOf:
          - title: id
            enum:
            - id
            - id asc
            - id desc
          - title: modified
            enum:
            - modified
            - modified asc
            - modified desc
          - title: created
            enum:
            - created
            - created asc
            - created desc
          - title: name
            enum:
            - name
            - name asc
            - name desc
          default: id
      tags:
      - Products
      responses:
        '200':
          description: Successful response for product list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCollection'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    post:
      summary: Create a product.
      operationId: createResourceProduct
      tags:
      - Products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '201':
          description: Product creation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
  /product/{id}:
    get:
      summary: Get a specific product.
      operationId: getResourceProduct
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/idInPath'
      responses:
        '200':
          description: Successfully retrieve a specific product
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    put:
      summary: Update a specific product.
      operationId: updateResourceProduct
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/idInPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: Product update response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    delete:
      summary: Delete a specific product.
      operationId: deleteResourceProduct
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/idInPath'
      responses:
        '204':
          $ref: '#/components/responses/deleteSuccess'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
components:
  schemas:
    Product:
      title: Product
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        created:
          $ref: '#/components/schemas/ServerTimestamp'
        modified:
          $ref: '#/components/schemas/ServerTimestamp'
        hidden:
          $ref: '#/components/schemas/IsHidden'
        type:
          $ref: '#/components/schemas/NullableId'
        name:
          type: string
          maxLength: 128
        price:
          $ref: '#/components/schemas/PositiveMoneyAmount'
        manualEntry:
          type: boolean
        descriptionHtml:
          type: string
          maxLength: 16777215
          nullable: true
        sku:
          type: string
          maxLength: 48
          nullable: true
        taxable:
          type: boolean
          default: false
        deliverable:
          type: boolean
          default: false
        vendorId:
          $ref: '#/components/schemas/NullableId'
        expenseCategoryId:
          $ref: '#/components/schemas/NullableId'
        expenseDueFrom:
          type: string
          enum:
          - JobDate
          - Booking
          - Never
          default: Never
        expenseDuePeriod:
          type: number
          maxLength: 5
        expenseDuePeriodType:
          type: string
          enum:
          - Days
          - Weeks
          - Months
          default: Days
        expenses:
          $ref: '#/components/schemas/ProductExpense'
    ProductExpense:
      title: Product Expense
      description: Array of product expenses
      type: array
      nullable: true
      items:
        type: object
        properties:
          memo:
            type: string
          amount:
            $ref: '#/components/schemas/PositiveMoneyAmount'
    IsHidden:
      title: Hidden attribute
      description: Whether or not the object is hidden.
      type: boolean
      example: false
      readOnly: true
    NullableId:
      title: Entity Identifier that might be null instead
      description: A ULID entity identifier that is nullable.
      type: string
      format: ulid
      nullable: true
      example: 01fqcr215r79p3h19crqbpzwzh
    ErrorValidation:
      description: A validation error.
      type: object
      properties:
        type:
          description: A namespace URI uniquely identifying the error type.
          type: string
          enum:
          - validation-error
        title:
          description: A short description of the error encountered.
          type: string
          example: Validation Error
        detail:
          description: Breakdown of what fields valid validation and why
          type: object
        status:
          description: The HTTP status code associated with this error.
          type: integer
          example: 400
    Id:
      title: Entity Identifier
      description: A lowercase [ULID](https://github.com/ulid/spec) entity identifier
      type: string
      format: ulid
      example: 01h35ccwymj5ctckp8px1azhg6
      readOnly: true
    ResourceType:
      title: Resource Type
      description: The type of resource represented.
      type: string
      example: resource-type
    Error:
      description: An error.
      type: object
      properties:
        type:
          description: A namespace URI uniquely identifying the error type.
          type: string
          enum:
          - unknown
          - quota-limit
          - not-implemented
        title:
          description: A short description of the error encountered.
          type: string
          example: Bad Request
        detail:
          description: A longer description of of the error encountered.
          type: string
          example: There was a problem with your request. Please see `info` for more information.
        status:
          description: The HTTP status code associated with this error.
          type: integer
          example: 400
    ServerTimestamp:
      title: Server Timestamp
      description: A server timestamp (always in UTC)
      type: string
      format: date-time
      readOnly: true
      example: '2020-08-01T17:32:32Z'
    ProductCollection:
      allOf:
      - properties:
          type:
            enum:
            - product-collection
          items:
            title: Product
            type: array
            items:
              $ref: '#/components/schemas/Product'
      - $ref: '#/components/schemas/List'
    List:
      title: Collection
      description: A collection (or list) of resources.
      type: object
      required:
      - type
      - items
      properties:
        meta:
          description: Metadata describing the current result set.
          type: object
          readOnly: true
          properties:
            currentPage:
              description: The current page of results returned.
              type: integer
            totalPages:
              description: 'The total number of pages in the result set. This is affected by

                the `pageSize` parameter (`totalItems / pageSize == totalPages`).'
              type: integer
            totalItems:
              description: 'The total number of items in the result set. This may be

                affected by active search/filter parameters.'
              type: integer
            rows:
              description: The number of rows returned per page for the current result set.
              type: integer
        type:
          $ref: '#/components/schemas/ResourceType'
        items:
          description: A collection of resources returned in the current result set.
          type: array
          items:
            type: object
    PositiveMoneyAmount:
      title: Positive numeric representing an amount in the studio's currency
      type: integer
      minimum: 0
      maximum: 99999999999
  responses:
    validationError:
      description: 'Validation error response. Check the `info.errors` property in the

        response for more details.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorValidation'
    tooManyRequestsError:
      description: Exceeded request quota, see Retry-After header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    deleteSuccess:
      description: The resource was successfully deleted.
  parameters:
    idInPath:
      name: id
      in: path
      description: ULID to perform an action on.
      schema:
        $ref: '#/components/schemas/Id'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Jobs & Contacts
  tags:
  - Jobs
  - Job Contacts
  - Job Worksheets
  - Contacts
  - Events
  - Files
  - Galleries
  - Notes
  - Orders
  - Payment
- name: Studio Settings
  tags:
  - Studio
  - Brands
  - Custom Fields
  - Discounts
  - Discount Types
  - Event Types
  - File Types
  - Job Closed Reasons
  - Job Roles
  - Job Types
  - Lead Sources
  - Lead Statuses
  - Payment Methods
  - Products
  - Product Types
  - Profit Centers
  - Tax Groups
  - Tax Rates
  - Timezones
  - Users
- name: API Resources
  tags:
  - Rest Hooks