VSCO Galleries API
The Galleries API from VSCO — 2 operation(s) for galleries.
OpenAPI Specification
openapi: 3.0.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:
schemas:
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
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
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
ResourceType:
title: Resource Type
description: The type of resource represented.
type: string
example: resource-type
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'
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'
GalleryCollection:
allOf:
- properties:
type:
enum:
- gallery-collection
items:
title: Galleries
type: array
items:
$ref: '#/components/schemas/Gallery'
- $ref: '#/components/schemas/List'
IsHidden:
title: Hidden attribute
description: Whether or not the object is hidden.
type: boolean
example: false
readOnly: true
Id:
title: Entity Identifier
description: A lowercase [ULID](https://github.com/ulid/spec) entity identifier
type: string
format: ulid
example: 01h35ccwymj5ctckp8px1azhg6
readOnly: true
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:
nullable: true
type: array
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
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.
nullable: true
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
format: float
minimum: 0
maximum: 100
nullable: true
focalPointY:
description: The Y coordinate of the focal point of the cover photo in the range of 0 to 1.
type: number
format: float
minimum: 0
maximum: 100
nullable: true
remoteId:
description: The remote ID of the cover photo. This ID does not need to be unique.
type: string
maxLength: 32
nullable: true
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
nullable: true
default: true
password:
description: A reusable plain-text passcode for unlocking the gallery. This pass code may be given to invited users.
type: string
nullable: true
maxLength: 255
category:
description: The category of this gallery. Galleries may be grouped by this category text in future client portal designs.
type: string
maxLength: 255
nullable: true
releaseDate:
description: The date this gallery will be released to the public. Useful in automations or email tokens.
type: string
format: date
nullable: true
eventDate:
description: The date of the event this gallery is for. Useful in automations or email tokens.
type: string
format: date
nullable: true
expirationDate:
description: The date this gallery will expire and no longer be accessible. Useful in automations or email tokens.
type: string
format: date
nullable: true
orderDueDate:
description: The date that orders for this gallery are due by. Useful in automations or email tokens.
type: string
format: date
nullable: true
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
minLength: 1
maxLength: 255
nullable: true
headline:
description: The headline of this gallery. Prioritized over name when displayed to the user.
type: string
maxLength: 255
nullable: true
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
maxLength: 24
nullable: true
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
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
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
parameters:
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
externalMappingId:
name: externalMappingId
in: query
description: Filter objects by an external id for this provider.
schema:
type: string
maxLength: 64
default: null
page:
name: page
in: query
description: The page of results to return.
schema:
type: integer
default: 1
minimum: 1
includeHidden:
name: includeHidden
in: query
description: Include objects that have been hidden
schema:
type: boolean
default: false
example: false
idInPath:
name: id
in: path
description: ULID to perform an action on.
schema:
$ref: '#/components/schemas/Id'
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.
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