VSCO Galleries API

openapi: 3.2.0
info:
  title: VSCO Workspace Brands Galleries 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: Galleries
paths:
  /gallery:
    get:
      summary: List of a studio’s galleries
      operationId: listResourceGallery
      x-entity: Gallery
      tags:
      - Galleries
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/includeHidden'
      - $ref: '#/components/parameters/externalMappingId'
      - 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: name asc
      responses:
        '200':
          description: Gallery list response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryCollection'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    post:
      summary: Create an gallery.
      operationId: createResourceGallery
      tags:
      - Galleries
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Gallery'
      responses:
        '201':
          description: Gallery creation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gallery'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
  /gallery/{id}:
    get:
      summary: Get a specific gallery
      operationId: getResourceGallery
      tags:
      - Galleries
      parameters:
      - $ref: '#/components/parameters/idInPath'
      responses:
        '200':
          description: Fetch a specific gallery entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gallery'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    put:
      summary: Update a specific gallery.
      operationId: updateResourceGallery
      tags:
      - Galleries
      parameters:
      - $ref: '#/components/parameters/idInPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Gallery'
      responses:
        '200':
          description: gallery response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Gallery'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    delete:
      summary: Delete an gallery.
      operationId: deleteResourceGallery
      tags:
      - Galleries
      parameters:
      - $ref: '#/components/parameters/idInPath'
      responses:
        '204':
          $ref: '#/components/responses/deleteSuccess'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
components:
  parameters:
    externalMappingId:
      name: externalMappingId
      in: query
      description: Filter objects by an external id for this provider.
      schema:
        type: string
        maxLength: 64
        default: null
    includeHidden:
      name: includeHidden
      in: query
      description: Include objects that have been hidden
      schema:
        type: boolean
        default: false
        example: false
    page:
      name: page
      in: query
      description: The page of results to return.
      schema:
        type: integer
        default: 1
        minimum: 1
    idInPath:
      name: id
      in: path
      description: ULID to perform an action on.
      schema:
        $ref: '#/components/schemas/Id'
    pageSize:
      name: pageSize
      in: query
      description: Number of results per page to return in the collection.
      schema:
        type: integer
        minimum: 10
        maximum: 100
        default: 100
  schemas:
    Gallery:
      title: Gallery
      type: object
      required:
      - name
      - clientUrl
      - adminUrl
      properties:
        links:
          $ref: '#/components/schemas/Links'
        id:
          $ref: '#/components/schemas/Id'
        created:
          $ref: '#/components/schemas/ServerTimestamp'
        modified:
          $ref: '#/components/schemas/ServerTimestamp'
        hidden:
          $ref: '#/components/schemas/IsHidden'
        externalMappings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ExternalMapping'
        jobId:
          $ref: '#/components/schemas/NullableId'
        eventId:
          $ref: '#/components/schemas/NullableId'
        remoteId:
          description: The remote ID of this gallery. <b>This value must be unique for the studio.</b>
          type: string
          maxLength: 36
        remoteCreated:
          allOf:
          - description: The date and time this gallery was created on the remote service.
          - title: A date time (in UTC)
            description: 'A date time string consisting of year, month and day along with hour,

              minute and second in UTC.'
            type: string
            format: date-time
            example: '2020-06-17T13:06:22+00:00'
        status:
          type: string
          default: active
          enum:
          - pre-release
          - active
          - inactive
          - archived
        coverPhoto:
          type:
          - object
          - 'null'
          description: When creating or updating a gallery, this object may be used to import a cover photo. If the gallery does not yet have a covor photo, VSCO Workspace will use a placeholder graphic.
          required:
          - remoteUrl
          properties:
            focalPointX:
              description: The X coordinate of the focal point of the cover photo in the range of 0 to 1.
              type:
              - number
              - 'null'
              format: float
              minimum: 0
              maximum: 100
            focalPointY:
              description: The Y coordinate of the focal point of the cover photo in the range of 0 to 1.
              type:
              - number
              - 'null'
              format: float
              minimum: 0
              maximum: 100
            remoteId:
              description: The remote ID of the cover photo. This ID does not need to be unique.
              type:
              - string
              - 'null'
              maxLength: 32
            remoteUrl:
              description: The URL of the cover photo for this gallery. The URL uses Uploadcare's responsive image CDN, allowing [on-the-fly operations](https://uploadcare.com/docs/cdn-operations/) to  be added to the URL. If the user cropped the photo in VSCO Workspace, the corrosponding crop  operations may be auto-appended to the returned URL.<br> <br> Providing a VSCO Workspace URL on creation or update will cause the `coverPhoto` property to  be ignored (re-using a VSCO Workspace URL with a second gallery is not supported at this time).<br> <br> Providing a non-VSCO Workspace URL will cause the image at the URL to be fetched and stored in VSCO Workspace.  The imported file will be used with our Uploadcare responsive image hosting CDN.  <b>Some plans may have storage quotas, so avoid importing large files or originals.</b><br> <br> VSCO Workspace is contractually prevented from implementing a gallery service at this time, so we have no use for large images or originals and will always downsample images to below 2,000 pixels in any direction.
              type: string
              format: uri
        public:
          description: Whether this gallery is publicly accessible.
          type: boolean
        requiresPassword:
          type:
          - boolean
          - 'null'
          default: true
        password:
          description: A reusable plain-text passcode for unlocking the gallery. This pass code may be given to invited users.
          type:
          - string
          - 'null'
          maxLength: 255
        category:
          description: The category of this gallery. Galleries may be grouped by this category text in future client portal designs.
          type:
          - string
          - 'null'
          maxLength: 255
        releaseDate:
          description: The date this gallery will be released to the public. Useful in automations or email tokens.
          type:
          - string
          - 'null'
          format: date
        eventDate:
          description: The date of the event this gallery is for. Useful in automations or email tokens.
          type:
          - string
          - 'null'
          format: date
        expirationDate:
          description: The date this gallery will expire and no longer be accessible. Useful in automations or email tokens.
          type:
          - string
          - 'null'
          format: date
        orderDueDate:
          description: The date that orders for this gallery are due by. Useful in automations or email tokens.
          type:
          - string
          - 'null'
          format: date
        orderCount:
          description: The number of orders placed for this gallery.
          type: integer
          default: 0
        photoCount:
          description: The number of photos in this gallery.
          type: integer
          default: 0
        visitorCount:
          description: The number of visitors to this gallery.
          type: integer
          default: 0
        name:
          description: The name of this gallery.
          type:
          - string
          - 'null'
          minLength: 1
          maxLength: 255
        headline:
          description: The headline of this gallery. Prioritized over name when displayed to the user.
          type:
          - string
          - 'null'
          maxLength: 255
        slug:
          description: The URL path slug for this gallery. This is the URL-friendly version of the name and must contain only letters, numbers, dashes, and underscores. When setting this value, it will be converted to lowercase and any illegal characters stripped.
          type:
          - string
          - 'null'
          maxLength: 24
        clientUrl:
          description: The URL of this gallery. Will be used for links in emails and the client portal.
          type: string
          format: uri
          maxLength: 2000
        adminUrl:
          description: The internal URL of this gallery in the remote admin portal. May be used to link employees to the gallery administration interface in the remote service.
          type: string
          format: uri
          maxLength: 2000
    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
    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
      - 'null'
      format: ulid
      example: 01fqcr215r79p3h19crqbpzwzh
    Link:
      title: Hypermedia Link Relationship
      description: 'The target URL indicated in the `href` property is related to the

        current resource according to the defined semantics of the link

        property name.'
      type: object
      required:
      - href
      properties:
        href:
          description: The hypertext reference to the API resource at tave.io.
          type: string
          format: uri
        managerHref:
          description: The URL to this item inside the Manager application at workspace.vsco.co.
          type: string
          format: uri
        clientHref:
          description: The URL to this item in Client Access, if available.
          type: string
          format: uri
    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
    ExternalMapping:
      title: External Mapping
      description: 'This is used to relate a unique entity id in an external system to an

        entity inside of VSCO Workspace.  These objects can not be updated currently.'
      type: object
      required:
      - id
      - url
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 64
        url:
          description: The url to the remote item.
          type: string
          format: uri
          minLength: 12
          maxLength: 255
    ServerTimestamp:
      title: Server Timestamp
      description: A server timestamp (always in UTC)
      type: string
      format: date-time
      readOnly: true
      example: '2020-08-01T17:32:32Z'
    Id:
      title: Entity Identifier
      description: A lowercase [ULID](https://github.com/ulid/spec) entity identifier
      type: string
      format: ulid
      example: 01h35ccwymj5ctckp8px1azhg6
      readOnly: true
    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
    ResourceType:
      title: Resource Type
      description: The type of resource represented.
      type: string
      example: resource-type
    GalleryCollection:
      allOf:
      - properties:
          type:
            enum:
            - gallery-collection
          items:
            title: Galleries
            type: array
            items:
              $ref: '#/components/schemas/Gallery'
      - $ref: '#/components/schemas/List'
    Links:
      title: Link Relationships
      description: 'Each property defines a hypertext link relationship as indicated by a

        link object or array of link objects. The target URL of each hypertext

        link relationship is related to the current resource according to the

        defined semantics of the link relationship property name.'
      readOnly: true
      required:
      - self
      type: object
      example: "\"self\": {\n  \"href\": \"https://example.com/object-endpoint/03c41781-f06f-4402-a5d9-1c30ccb4db29\",\n  \"title\": \"Example Link Relationship\",\n  \"type\": \"application/json\",\n}"
      properties:
        self:
          allOf:
          - title: Self
            description: The target URL is the current resource's own location.
          - $ref: '#/components/schemas/Link'
  responses:
    deleteSuccess:
      description: The resource was successfully deleted.
    tooManyRequestsError:
      description: Exceeded request quota, see Retry-After header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    validationError:
      description: 'Validation error response. Check the `info.errors` property in the

        response for more details.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorValidation'
  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