> ## Documentation Index
> Fetch the complete documentation index at: https://developers.dock.us/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an asset
> Create an asset. For file-backed types (pdf, image, video, audio, docx, ppt, xlsx, htmlPage), first create a file via POST /files and PUT the bytes to its upload URL, then pass the file id here. Link and embed assets are created from a URL (or custom embed code) directly. Office documents (docx, ppt, xlsx) are converted to a PDF rendition asynchronously and are returned as the corresponding `microsoft*EmbedPdf` asset type — poll GET /files/{id} on the asset's file to track conversion.
export const RateLimit = ({perMinute = 120}) =>
This endpoint is rate limited to {perMinute} requests per minute per
company. See Rate limits for details.
;
See [Uploading files](/api-reference/uploading-files) for the end-to-end upload flow.
## OpenAPI
````yaml post /assets
openapi: 3.1.0
info:
title: Dock API
description: >-
The Dock API is a RESTful API that allows you to interact with Dock in a
programmatic way
termsOfService: https://www.dock.us/legal/terms
contact:
name: API Support
email: developers@dock.us
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: 1.0.0
servers:
- url: https://api.dock.us/{version}
description: Production server
variables:
version:
default: v1
enum:
- v1
security:
- bearerAuth: []
tags:
- name: Status check
description: API to check if the API is up
- name: Accounts
description: API to manage accounts
- name: Assets
description: API to manage assets
- name: Asset share links
description: API to retrieve asset share links
- name: Files
description: API to manage files
- name: Forms
description: API to retrieve forms and their responses
- name: Meetings
description: API to manage meetings and call transcripts
- name: Tags
description: API to manage tags
- name: Users
description: API to manage users
- name: Workspaces
description: API to manage workspaces
- name: Templates
description: API to manage templates
- name: Workspace pages
description: API to manage workspace pages
- name: Workspace plans
description: API to manage workspace plans
- name: Workspace plan tasks
description: API to manage workspace plan tasks
- name: Workspace sections
description: API to manage workspace sections
paths:
/assets:
post:
tags:
- Assets
description: >-
Create an asset. For file-backed types (pdf, image, video, audio, docx,
ppt, xlsx, htmlPage), first create a file via POST /files and PUT the
bytes to its upload URL, then pass the file id here. Link and embed
assets are created from a URL (or custom embed code) directly. Office
documents (docx, ppt, xlsx) are converted to a PDF rendition
asynchronously and are returned as the corresponding
`microsoft*EmbedPdf` asset type — poll GET /files/{id} on the asset's
file to track conversion.
parameters:
- $ref: '#/components/parameters/assetProperties'
requestBody:
description: Asset to create
required: true
content:
application/json:
schema:
type: object
required:
- type
- name
properties:
type:
type: string
description: Type of asset to create
enum:
- pdf
- image
- video
- audio
- docx
- ppt
- xlsx
- htmlPage
- link
- embed
example: pdf
name:
type: string
description: Name of the asset
example: Sales deck
description:
type: string
description: Description of the asset
tagIds:
type: array
description: >-
Ids of existing tags to attach to the asset (create tags via
POST /tags)
items:
type: string
example:
- RiHO4e0Ju3DS
isInternal:
type: boolean
description: Whether the asset is for internal use only
default: false
fileId:
type: string
description: >-
Id of an uploaded file (from POST /files). Required for pdf,
image, video, audio, docx, ppt, xlsx and htmlPage assets.
The file's bytes must already be uploaded, its mimeType must
match the asset type, and it can only back one asset.
example: f9Ghw2n0Ju3D
url:
type: string
description: >-
Source URL. Required for link assets; for embed assets
provide either url or customCode (not both).
example: https://example.com/pricing
customCode:
type: string
description: >-
Custom embed HTML. Only for embed assets, mutually exclusive
with url.
example:
metadata:
type: object
description: >-
Optional media metadata for file-backed assets. The server
extracts pdf/image metadata automatically when omitted;
video/audio dimensions and duration can only come from the
caller.
properties:
width:
type: integer
description: Width in pixels (image, video)
height:
type: integer
description: Height in pixels (image, video)
duration:
type: number
description: Duration in seconds (video, audio)
pages:
type: integer
description: Page count (pdf)
oneOf:
- title: File-backed asset
properties:
type:
enum:
- pdf
- image
- video
- audio
- docx
- ppt
- xlsx
- htmlPage
required:
- fileId
- title: Link asset
properties:
type:
enum:
- link
required:
- url
- title: Embed asset from a URL
properties:
type:
enum:
- embed
customCode:
not: {}
required:
- url
- title: Embed asset from custom code
properties:
type:
enum:
- embed
url:
not: {}
required:
- customCode
responses:
'200':
description: Asset created
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
asset:
$ref: '#/components/schemas/Asset'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
components:
parameters:
assetProperties:
name: properties
in: query
description: Select the asset properties that should be returned
schema:
type: array
items:
type: string
enum:
- name
- description
- updatedAt
- createdAt
- views
- shares
- assetType
- assetUrl
- isInternal
- transcript
- tags.title
- tags.createdAt
- tags.updatedAt
schemas:
Asset:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
tags:
type: array
description: Tags of the asset
items:
$ref: '#/components/schemas/Tag'
object:
type: string
description: Type of the object
enum:
- asset
example: asset
readOnly: true
url:
type: string
example: https://api.dock.us/v1/assets/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
name:
type: string
description: Name of the asset
example: Logo
description:
type: string
description: Description of the asset
example: Logo of the asset
nullable: true
transcript:
type:
- string
- 'null'
description: Transcript extracted from the asset file
views:
type: integer
description: Number of views
example: 100
shares:
type: integer
description: Number of shares
example: 100
assetType:
type: string
description: Type of the asset
enum:
- image
- pdf
- link
- video
- audio
- embed
- htmlPage
- googleDocEmbed
- googleSheetEmbed
- googleSlidesEmbed
- microsoftWordEmbed
- microsoftExcelEmbed
- microsoftPowerPointEmbed
- googleDocEmbedPdf
- googleSheetEmbedPdf
- googleSlidesEmbedPdf
- microsoftWordEmbedPdf
- microsoftExcelEmbedPdf
- microsoftPowerPointEmbedPdf
example: image
assetUrl:
type: string
format: uri
description: URL to the asset
example: https://dock.us/logo.png
isInternal:
type: boolean
description: Whether the asset is restricted to internal use
example: false
BaseObject:
type: object
properties:
id:
$ref: '#/components/schemas/Id'
updatedAt:
type: string
format: date-time
description: Last updated date
example: '2021-01-01T00:00:00.000Z'
readOnly: true
createdAt:
type: string
format: date-time
description: Created at date
example: '2021-01-01T00:00:00.000Z'
readOnly: true
Tag:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- tag
example: tag
readOnly: true
url:
type: string
example: https://api.dock.us/v1/tags/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
title:
type: string
description: Title of the tag
example: Logo
Id:
type: string
description: Id of the object
example: RiHO4e0Ju3DS
readOnly: true
responses:
'400':
description: >-
The server cannot or will not process the request due to something that
is perceived to be a client error (e.g., malformed request syntax,
invalid request message framing, or deceptive request routing)
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- BAD_REQUEST
description: A short code indicating the error code returned
example: BAD_REQUEST
message:
type: string
description: A human readable explanation of what went wrong
example: >-
The request could not be understood or was missing
required parameters
required:
- code
- message
required:
- error
'401':
description: >-
Although the HTTP standard specifies "unauthorized", semantically this
response means "unauthenticated". That is, the client must authenticate
itself to get the requested response
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- UNAUTHORIZED
description: A short code indicating the error code returned
example: UNAUTHORIZED
message:
type: string
description: A human readable explanation of what went wrong
example: >-
Access denied. You are not authorized to access this
resource
required:
- code
- message
required:
- error
'403':
description: >-
The client does not have access rights to the content; that is, it is
unauthorized, so the server is refusing to give the requested resource.
Unlike 401 Unauthorized, the client's identity is known to the server
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- FORBIDDEN
description: A short code indicating the error code returned
example: FORBIDDEN
message:
type: string
description: A human readable explanation of what went wrong
example: Access to this resource is restricted
required:
- code
- message
required:
- error
'404':
description: The server cannot find the requested resource
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- NOT_FOUND
description: A short code indicating the error code returned
example: NOT_FOUND
message:
type: string
description: A human readable explanation of what went wrong
example: The requested resource could not be found
required:
- code
- message
required:
- error
'429':
description: >-
The user has sent too many requests in a given amount of time ("rate
limiting")
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- RATE_LIMIT_EXCEEDED
description: A short code indicating the error code returned
example: RATE_LIMIT_EXCEEDED
message:
type: string
description: A human readable explanation of what went wrong
example: Rate limit exceeded. Please try again later
required:
- code
- message
required:
- error
'500':
description: The server has encountered a situation it does not know how to handle
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- INTERNAL_SERVER_ERROR
description: A short code indicating the error code returned
example: INTERNAL_SERVER_ERROR
message:
type: string
description: A human readable explanation of what went wrong
example: >-
The server has encountered a situation it does not know
how to handle
required:
- code
- message
required:
- error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````