> ## 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.
# Connect a workspace
> Connect a workspace to another workspace, so they share one link, one sidebar and one set of access settings, the same as **Add workspace** in Dock. `{id}` is any workspace in the group to connect to; a workspace that isn't connected to anything yet becomes the group's homepage.
Provide exactly one of:
- `workspaceId` to connect an existing workspace. It must belong to the same account and must not already be connected to other workspaces (disconnect it in Dock first). It takes over the group's access settings, and if it is not published yet it is published with the homepage's users and domains, replacing its own. Connecting a workspace that is already in the group returns `200` and changes nothing.
- `templateId` to create a new workspace from a template inside the group. It belongs to the group's account and is published with the group's access settings. Unless `workspaceUsers` or `workspaceDomains` are provided, everyone with access to a workspace in the group gets the same access to the new one. Templates that require a deal need `hubspotDealId` or `salesforceOpportunityId`. This uses one workspace API credit, and companies on the free plan are limited to 10 workspaces total (active and archived combined).
The company must be verified to publish workspaces; otherwise this endpoint returns 403 FORBIDDEN.
export const RateLimit = ({perMinute = 120}) =>
This endpoint is rate limited to {perMinute} requests per minute per
company. See Rate limits for details.
;
## OpenAPI
````yaml post /workspaces/{id}/connected-workspaces
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:
/workspaces/{id}/connected-workspaces:
post:
tags:
- Workspaces
description: >-
Connect a workspace to another workspace, so they share one link, one
sidebar and one set of access settings, the same as **Add workspace** in
Dock. `{id}` is any workspace in the group to connect to; a workspace
that isn't connected to anything yet becomes the group's homepage.
Provide exactly one of:
- `workspaceId` to connect an existing workspace. It must belong to the
same account and must not already be connected to other workspaces
(disconnect it in Dock first). It takes over the group's access
settings, and if it is not published yet it is published with the
homepage's users and domains, replacing its own. Connecting a workspace
that is already in the group returns `200` and changes nothing.
- `templateId` to create a new workspace from a template inside the
group. It belongs to the group's account and is published with the
group's access settings. Unless `workspaceUsers` or `workspaceDomains`
are provided, everyone with access to a workspace in the group gets the
same access to the new one. Templates that require a deal need
`hubspotDealId` or `salesforceOpportunityId`. This uses one workspace
API credit, and companies on the free plan are limited to 10 workspaces
total (active and archived combined).
The company must be verified to publish workspaces; otherwise this
endpoint returns 403 FORBIDDEN.
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/workspaceProperties'
requestBody:
required: true
content:
application/json:
schema:
type: object
oneOf:
- required:
- workspaceId
- required:
- templateId
properties:
workspaceId:
type: string
description: ID of an existing workspace to connect
example: PkT2mVq81xLc
templateId:
type: string
description: ID of the template to create the connected workspace from
example: TmPl4t3Id001
name:
type: string
description: >-
Name of the new workspace. Defaults to the template's
workspace title. Only with `templateId`
example: Acme Onboarding
hubspotDealId:
type: string
description: >-
ID of the HubSpot deal to link the new workspace to. The
deal must belong to the group account's HubSpot company.
Only with `templateId`
example: '1234567890'
salesforceOpportunityId:
type: string
description: >-
ID of the Salesforce opportunity to link the new workspace
to. The opportunity must belong to the group account's
Salesforce account. Only with `templateId`
example: 0065g00000XyZabAAF
startDate:
type: string
format: date
description: >-
The start date of the new workspace in `YYYY-MM-DD` format.
Only with `templateId`
example: '2026-10-06'
targetEndDate:
type: string
format: date
description: >-
The target end date of the new workspace in `YYYY-MM-DD`
format. Only with `templateId`
example: '2026-12-15'
actualEndDate:
type: string
format: date
description: >-
The actual end date of the new workspace in `YYYY-MM-DD`
format. Only with `templateId`
example: '2026-12-01'
workspaceUsers:
type: array
description: >-
Users of the new workspace, instead of the group's. At least
one user or domain must have the `owner` role. Only with
`templateId`
items:
type: object
required:
- email
- role
properties:
email:
type: string
format: email
description: Email of the user
role:
$ref: '#/components/schemas/WorkspaceRole'
example:
- email: jane@acme.com
role: owner
workspaceDomains:
type: array
description: >-
Domains of the new workspace, instead of the group's. Only
with `templateId`
items:
type: object
required:
- domain
- role
properties:
domain:
type: string
format: hostname
description: Domain whose users get access
role:
$ref: '#/components/schemas/WorkspaceRole'
example:
- domain: acme.com
role: collaborator
responses:
'200':
description: The workspace was already connected; nothing changed
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
workspace:
$ref: '#/components/schemas/Workspace'
'201':
description: >-
The connected workspace (the existing one, or the one created from
the template)
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
workspace:
$ref: '#/components/schemas/Workspace'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'409':
description: >-
The workspace is already connected to other workspaces. Disconnect
it in Dock first
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
components:
parameters:
id:
name: id
in: path
example: RiHO4e0Ju3DS
required: true
description: Unique identifier
schema:
type: string
example: RiHO4e0Ju3DS
workspaceProperties:
name: properties
in: query
description: Select the workspace properties that should be returned
schema:
type: array
items:
type: string
enum:
- accountId
- name
- workspaceUrl
- templateId
- startDate
- targetEndDate
- actualEndDate
- projectAge
- taskProgress
- lastContactView
- totalViews
- totalActions
- totalTimeSpent
- contactsCount
- account.name
- account.website
- account.ownerId
- account.logo
- account.salesforceAccountId
- account.hubspotCompanyId
- account.createdAt
- account.updatedAt
- customFields.name
- customFields.type
- customFields.variableName
- customFields.value
- workspaceDomains.domain
- workspaceDomains.role
- workspaceDomains.createdAt
- workspaceDomains.updatedAt
- workspaceUsers.role
- workspaceUsers.createdAt
- workspaceUsers.updatedAt
- workspaceUsers.user.firstName
- workspaceUsers.user.lastName
- workspaceUsers.user.avatar
- workspaceUsers.user.email
- workspaceUsers.user.name
- workspaceUsers.user.createdAt
- workspaceUsers.user.updatedAt
- deal.name
- deal.amount
- deal.closeDate
- deal.createdDate
- deal.type
- deal.stage
- deal.hubspotDealId
- deal.salesforceOpportunityId
schemas:
WorkspaceRole:
type: string
description: Role of the user to access the workspace
enum:
- owner
- editor
- collaborator
- viewer
- commenter
example: owner
Workspace:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
workspaceUsers:
type: array
description: Users of the workspace
items:
$ref: '#/components/schemas/WorkspaceUser'
workspaceDomains:
type: array
description: Domains of the workspace
items:
$ref: '#/components/schemas/WorkspaceDomain'
account:
$ref: '#/components/schemas/Account'
object:
type: string
description: Type of the object
enum:
- workspace
example: workspace
readOnly: true
url:
type: string
example: https://api.dock.us/v1/workspaces/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
name:
type: string
description: Name of the workspace
example: Customer Onboarding
workspaceUrl:
type: string
description: URL of the workspace
example: https://acme.dock.us/customer-onboarding-vRQgIvscHAiO
templateId:
type: string
description: ID of the associated template
example: RiHO4e0Ju3DS
nullable: true
startDate:
type: string
format: date
description: Start date of the workspace
example: '2024-01-01'
nullable: true
targetEndDate:
type: string
format: date
description: Target end date of the workspace
example: '2024-01-01'
nullable: true
actualEndDate:
type: string
format: date
description: Actual end date of the workspace
example: '2024-01-01'
nullable: true
projectAge:
type: number
description: Age of the project
example: 100
taskProgress:
type: string
description: Progress of all the tasks
example: '50'
lastContactView:
type: string
format: date-time
description: Last contact view date of the workspace
example: '2024-01-01T00:00:00Z'
nullable: true
totalViews:
type: number
description: Total views of the workspace
example: 100
totalActions:
type: number
description: Total actions of the workspace
example: 100
totalTimeSpent:
type: number
description: Total time spent of the workspace
example: 100
contactsCount:
type: number
description: Number of contacts associated with the workspace
example: 100
deal:
$ref: '#/components/schemas/Deal'
- type: object
properties:
customFields:
type: array
description: Custom fields associated with the workspace
items:
$ref: '#/components/schemas/CustomFieldWithValue'
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
WorkspaceUser:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- workspace-user
example: workspace-user
readOnly: true
url:
type: string
example: https://api.dock.us/v1/workspace-users/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
role:
$ref: '#/components/schemas/WorkspaceRole'
user:
$ref: '#/components/schemas/User'
WorkspaceDomain:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- workspace-domain
example: workspace-domain
readOnly: true
url:
type: string
example: https://api.dock.us/v1/workspace-domains/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
role:
$ref: '#/components/schemas/WorkspaceRole'
domain:
type: string
description: Domain of the workspace user
format: hostname
example: dock.us
Account:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- account
example: account
readOnly: true
url:
type: string
example: https://api.dock.us/v1/accounts/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
name:
type: string
description: Name of the account
example: Dock
website:
type: string
format: uri
description: Website of the account
example: https://dock.us
nullable: true
ownerId:
type: string
description: Owner ID of the account
example: RiHO4e0Ju3DS
logo:
type: string
format: uri
description: Logo of the account
example: https://dock.us/logo.png
nullable: true
salesforceAccountId:
type: string
description: Salesforce account ID of the account
example: 0015f00000Bg59dAAB
nullable: true
hubspotCompanyId:
type: string
description: HubSpot company ID of the account
example: '8662045446'
nullable: true
Deal:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- deal
example: deal
readOnly: true
url:
type: string
example: https://api.dock.us/v1/deals/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
createdDate:
type: string
format: date-time
description: Created date of the deal
example: '2024-01-01T00:00:00Z'
nullable: true
closeDate:
type: string
format: date-time
description: Close date of the deal
example: '2024-01-01T00:00:00Z'
nullable: true
name:
type: string
description: Name of the deal
example: Deal 1
nullable: true
amount:
type: integer
description: Amount of the deal
example: '100000'
nullable: true
type:
type: string
description: Type of the deal
example: New Business
nullable: true
stage:
type: string
description: Stage of the deal
example: Proposal Sent
nullable: true
oneOf:
- properties:
hubspotDealId:
type: string
description: HubSpot deal ID
example: '1234567890'
nullable: true
additionalProperties: false
- properties:
salesforceOpportunityId:
type: string
description: Salesforce opportunity ID
example: 0015f00000Bg59dAAB
nullable: true
additionalProperties: false
CustomFieldWithValue:
allOf:
- $ref: '#/components/schemas/CustomField'
- type: object
properties:
value:
type: string
description: >-
Value of the custom field. For `richText` fields this is
returned as HTML.
example: 'Yes'
Id:
type: string
description: Id of the object
example: RiHO4e0Ju3DS
readOnly: true
User:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- user
example: user
readOnly: true
url:
type: string
example: https://api.dock.us/v1/users/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
firstName:
type: string
description: First name of the user
example: John
nullable: true
lastName:
type: string
description: Last name of the user
example: Doe
nullable: true
avatar:
type: string
format: uri
description: Avatar of the user
example: https://dock.us/avatar.png
nullable: true
email:
type: string
description: Email of the user
example: john.doe@example.com
name:
type: string
description: Name of the user
example: John Doe
CustomField:
allOf:
- $ref: '#/components/schemas/BaseObject'
- type: object
properties:
object:
type: string
description: Type of the object
enum:
- custom-field
example: custom-field
readOnly: true
url:
type: string
example: https://api.dock.us/v1/custom-fields/RiHO4e0Ju3DS
description: URL to the resource
readOnly: true
variableName:
type: string
description: Variable name of the custom field
example: account.name
type:
type: string
description: Type of the custom field
example: singleCheckbox
enum:
- number
- date
- singleLineText
- multiLineText
- richText
- singleCheckbox
- multiCheckboxes
- dropdownSelect
- radioSelect
options:
type: array
description: For dropdown, radio, and checkbox custom fields, the options
nullable: true
items:
type: object
properties:
index:
type: integer
description: Index of the option
example: 1
label:
type: string
description: Label of the option
example: 'Yes'
value:
type: string
description: Value of the option
example: '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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.