OpenAPI Specification
openapi: 3.0.1
info:
title: Onshape REST Account Document API
description: '## Welcome to the Onshape REST API Explorer
**See the [API Explorer Guide](https://onshape-public.github.io/docs/api-intro/explorer/) for help navigating this page.**
### Using this page
1. Sign in to your [Onshape](https://cad.onshape.com) account in another tab.
2. Click the `Try it out` button below. It toggles to a `Cancel` button when selected.
### Authenticating
To authenticate your calls, click the `Authorize` button. See [API Explorer Guide: Authentication](https://onshape-public.github.io/docs/api-intro/explorer/#authentication) for details. Calls made when authenticated via API Keys or OAuth count against your annual [API limits](https://onshape-public.github.io/docs/auth/limits/#annual-api-call-limits).
* **Tip:** To ensure the current session isn''t used when trying other authentication techniques, make sure to [remove the Onshape cookie](https://support.google.com/chrome/answer/95647#zippy=%2Cdelete-cookies-from-a-site) as per the instructions for your browser, or use a private or incognito window.
### Additional resources
* [Onshape API Guide](https://onshape-public.github.io/docs/): Our full suite of developer guides, to be used as an accompaniment to this API Explorer.
* [Onshape Developer Portal](https://cad.onshape.com/appstore/dev-portal): The Onshape portal for managing your API keys, OAuth2 credentials, your Onshape applications, and your Onshape App Store entries.
* [Authentication Guide](https://onshape-public.github.io/docs/auth/): Our guide to using API keys, request signatures, and OAuth2 in your Onshape applications.'
termsOfService: https://www.onshape.com/legal/terms-of-use
contact:
email: api-support@onshape.zendesk.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.218.84032-34acba44be17
x-logo:
url: images/logo-onshape-gray-green-nav-bar.svg
backgroundColor: '#ffffff'
altText: Onshape
href: images/logo-onshape-gray-green-nav-bar.svg
x-indeterministic-schemas:
- BTDiffInfo
- BTParameterSpecArray-2600
- BTSplineDescription-2118
- NodeModel
- BTPFunctionDeclaration-246
- BTPFunctionOrPredicateDeclaration-247
- BTPExpression-9
- SkinModel
- BTMAnnotation-4664
x-filter-info: ?restUserRole=PUBLIC
servers:
- url: https://cad.onshape.com/api/v16
description: Current
security:
- BasicAuth: []
tags:
- name: Document
description: Create and manage documents.
paths:
/documents:
get:
tags:
- Document
summary: Get a list of documents that meet the criteria you specify.
operationId: getDocuments
parameters:
- name: q
in: query
description: Search for documents that contain the given string in the name. Search is not case-sensitive.
schema:
type: string
default: ''
- name: filter
in: query
description: 'Type of documents to search: `0: My Documents | 1: Created | 2: Shared | 3: Trash | 4: Public | 5: Recent | 6: By Owner | 7: By Company | 9: By Team`'
schema:
type: integer
format: int32
- name: owner
in: query
description: Owner ID. Can be a user ID, company ID, or team ID, depending on `ownerType`.
schema:
type: string
default: ''
- name: ownerType
in: query
description: 'Type of owner. `0: User | 1: Company | 2: Onshape`. If the owner is a teamId, leave this unspecified.'
schema:
type: integer
format: int32
default: 1
- name: sortColumn
in: query
description: Column by which to sort search results. `name | modifiedAt | createdAt (default) | email | modifiedBy | promotedAt`
schema:
type: string
default: createdAt
- name: sortOrder
in: query
description: Sort order. `desc` (descending, default), or `asc` (ascending).
schema:
type: string
default: desc
- name: label
in: query
description: Label
schema:
type: string
- name: project
in: query
description: Project
schema:
type: string
- name: parentId
in: query
description: Parent Id
schema:
type: string
- name: offset
in: query
description: Offset. Determines where search results begin. Default value is 0.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: Maximum number of results to return per page. Default value is 20 (also the maximum). Number of results returned can be less than this value. Use the `next` URL in the response to fetch the next page.
schema:
maximum: 20
minimum: 1
type: integer
format: int32
default: 20
responses:
'200':
description: Success!
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTGlobalTreeNodeListResponse'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
post:
tags:
- Document
summary: Create and upload a document.
description: The `name` field is required in the `BTDocumentParams` schema when creating a new document.
operationId: createDocument
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTDocumentParams'
required: true
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTDocumentInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Write
BasicAuth:
- OAuth2Write
x-BTVisibility: PRODUCTION
/documents/d/{did}/externaldata/{fid}:
get:
tags:
- Document
summary: Download external data file(s) associated with the document.
description: "* See [API Guide: Model Translation](https://onshape-public.github.io/docs/api-adv/translation/) for more details.\n* If downloading an exported file, poll the `requestState` in the translation response and wait for a result of `DONE` before attempting to download the file. \n* Use the `resultExternalDataIds` from the translation response as the foreign id (`{fid}`) in this API."
operationId: downloadExternalData
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: fid
in: path
required: true
schema:
type: string
- name: If-None-Match
in: header
schema:
type: string
responses:
'200':
description: Success!
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: string
format: binary
application/octet-stream:
schema:
type: string
format: binary
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/d/{did}/versions:
get:
tags:
- Document
summary: Retrieve versions by document ID.
operationId: getDocumentVersions
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: offset
in: query
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
schema:
maximum: 20
type: integer
format: int32
default: 0
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: array
items:
$ref: '#/components/schemas/BTVersionInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
post:
tags:
- Document
summary: Create version by document ID.
operationId: createVersion
parameters:
- name: did
in: path
required: true
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTVersionOrWorkspaceParams'
required: true
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTVersionInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Write
BasicAuth:
- OAuth2Write
x-BTVisibility: PRODUCTION
/documents/d/{did}/versions/{vid}:
get:
tags:
- Document
summary: Retrieve version by document ID and version ID.
operationId: getVersion
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: vid
in: path
required: true
schema:
type: string
- name: parents
in: query
schema:
type: boolean
default: false
- name: linkDocumentId
in: query
schema:
type: string
responses:
'200':
description: Success!
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTVersionInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/d/{did}/w/{wid}/e/{eid}/latestdocumentreferences:
post:
tags:
- Document
summary: Update external references to latest by document ID, workspace ID, and tab ID.
operationId: updateExternalReferencesToLatestDocuments
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wid
in: path
required: true
schema:
type: string
- name: eid
in: path
required: true
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTLinkToLatestDocumentParams'
responses:
'200':
description: Success!
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTLinkToLatestDocumentInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Write
BasicAuth:
- OAuth2Write
x-BTVisibility: PRODUCTION
/documents/d/{did}/w/{wid}/moveelement:
post:
tags:
- Document
summary: Move tab by document ID and workspace ID.
operationId: moveElementsToDocument
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wid
in: path
required: true
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTMoveElementParams'
required: true
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTMoveElementInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Write
BasicAuth:
- OAuth2Write
x-BTVisibility: PRODUCTION
/documents/d/{did}/w/{wid}/revertunchangedtorevisions:
post:
tags:
- Document
operationId: revertUnchangedToRevisions
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wid
in: path
required: true
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTRevertUnchangedParams'
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: array
items:
$ref: '#/components/schemas/BTUnchangedElementInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Write
BasicAuth:
- OAuth2Write
x-BTVisibility: PRODUCTION
/documents/d/{did}/w/{wid}/syncAppElements:
post:
tags:
- Document
operationId: syncAppElements
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wid
in: path
required: true
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTSyncAppElementParams'
required: true
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: object
deprecated: false
security:
- OAuth2:
- OAuth2Write
BasicAuth:
- OAuth2Write
x-BTVisibility: PRODUCTION
/documents/d/{did}/workspaces:
get:
tags:
- Document
summary: Retrieve workspaces by document ID.
operationId: getDocumentWorkspaces
parameters:
- name: did
in: path
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: array
items:
$ref: '#/components/schemas/BTWorkspaceInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
post:
tags:
- Document
summary: Create workspace by document ID.
operationId: createWorkspace
parameters:
- name: did
in: path
required: true
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTVersionOrWorkspaceParams'
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTWorkspaceInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Write
BasicAuth:
- OAuth2Write
x-BTVisibility: PRODUCTION
/documents/d/{did}/workspaces/{wid}:
delete:
tags:
- Document
summary: Delete workspace by document ID and workspace ID.
operationId: deleteWorkspace
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wid
in: path
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: object
deprecated: false
security:
- OAuth2:
- OAuth2Delete
BasicAuth:
- OAuth2Delete
x-BTVisibility: PRODUCTION
/documents/d/{did}/{wm}/{wmid}/documenthistory:
get:
tags:
- Document
summary: Retrieve document history by document ID and workspace or microversion ID.
operationId: getDocumentHistory
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wm
in: path
required: true
schema:
type: string
- name: wmid
in: path
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: array
items:
$ref: '#/components/schemas/BTDocumentHistoryInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/d/{did}/{wvm}/{wvmid}/contents:
get:
tags:
- Document
summary: Retrieve tabs and folders by document ID and workspace or version or microversion ID.
description: Returns information on tabs and folders in the document.
operationId: getDocumentContents
parameters:
- name: did
in: path
description: The id of the document in which to perform the operation.
required: true
schema:
type: string
- name: linkDocumentId
in: query
description: The id of the document through which the above document should be accessed; only applicable when accessing a version of the document. This allows a user who has access to document a to see data from document b, as long as document b has been linked to document a by a user who has permission to both.
schema:
type: string
default: ''
- name: wvm
in: path
description: Indicates which of workspace (w), version (v), or document microversion (m) id is specified below.
required: true
schema:
type: string
enum:
- w
- v
- m
- name: wvmid
in: path
description: The id of the workspace, version or document microversion in which the operation should be performed.
required: true
schema:
type: string
- name: elementType
in: query
description: If specified, information for elements of this type are returned. Note, the folder structure is not affected by this filter.
schema:
$ref: '#/components/schemas/GBTElementType'
- name: elementId
in: query
description: If specified, only the element with this id is returned. Note, the folder structure is not affected by this filter.
schema:
type: string
- name: withZipContents
in: query
description: When true, returns the names of the files inside each zip file tab. Ignored if the document contains more than 10 zip files.
schema:
type: boolean
default: false
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTDocumentContentsInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/d/{did}/{wvm}/{wvmid}/elements:
get:
tags:
- Document
summary: Retrieve tabs by document ID and workspace or version or microversion ID.
description: This endpoint only returns the tabs and not folders in the document. Use the [getDocumentContents](#/Document/getDocumentContents) endpoint to get information about folders and tabs.
operationId: getElementsInDocument
parameters:
- name: did
in: path
description: The id of the document in which to perform the operation.
required: true
schema:
type: string
- name: linkDocumentId
in: query
description: The id of the document through which the above document should be accessed; only applicable when accessing a version of the document. This allows a user who has access to document a to see data from document b, as long as document b has been linked to document a by a user who has permission to both.
schema:
type: string
default: ''
- name: wvm
in: path
description: Indicates which of workspace (w), version (v), or document microversion (m) id is specified below.
required: true
schema:
type: string
enum:
- w
- v
- m
- name: wvmid
in: path
description: The id of the workspace, version or document microversion in which the operation should be performed.
required: true
schema:
type: string
- name: elementType
in: query
schema:
type: string
default: ''
- name: elementId
in: query
schema:
type: string
default: ''
- name: withThumbnails
in: query
schema:
type: boolean
default: false
- name: withZipContents
in: query
description: When true, returns the names of the files inside each zip file tab. Ignored if the document contains more than 10 zip files.
schema:
type: boolean
default: false
responses:
'200':
description: Success!
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: array
items:
$ref: '#/components/schemas/BTDocumentElementInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/d/{did}/{wvm}/{wvmid}/unitinfo:
get:
tags:
- Document
summary: Get the selected units and precision by document ID and workspace or version or microversion ID.
operationId: getUnitInfo
parameters:
- name: did
in: path
description: The id of the document in which to perform the operation.
required: true
schema:
type: string
- name: linkDocumentId
in: query
description: The id of the document through which the above document should be accessed; only applicable when accessing a version of the document. This allows a user who has access to document a to see data from document b, as long as document b has been linked to document a by a user who has permission to both.
schema:
type: string
default: ''
- name: wvm
in: path
description: Indicates which of workspace (w), version (v), or document microversion (m) id is specified below.
required: true
schema:
type: string
enum:
- w
- v
- m
- name: wvmid
in: path
description: The id of the workspace, version or document microversion in which the operation should be performed.
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTUnitInfo'
deprecated: false
x-BTVisibility: PRODUCTION
/documents/d/{did}/{wv}/{wvid}/currentmicroversion:
get:
tags:
- Document
summary: Retrieve current microversion by document ID and workspace or version ID.
operationId: getCurrentMicroversion
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wv
in: path
required: true
schema:
type: string
- name: wvid
in: path
required: true
schema:
type: string
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTMicroversionInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/d/{did}/{wv}/{wvid}/e/{eid}/export:
post:
tags:
- Document
summary: Export document by document ID, workspace or version ID, and tab ID.
operationId: export2Json
parameters:
- name: did
in: path
description: The id of the document in which to perform the operation.
required: true
schema:
type: string
- name: linkDocumentId
in: query
description: The id of the document through which the above document should be accessed; only applicable when accessing a version of the document. This allows a user who has access to document a to see data from document b, as long as document b has been linked to document a by a user who has permission to both.
schema:
type: string
default: ''
- name: wv
in: path
description: Indicates which of workspace (w) or version (v) id is specified below.
required: true
schema:
type: string
enum:
- w
- v
- name: wvid
in: path
description: The id of the workspace, version in which the operation should be performed.
required: true
schema:
type: string
- name: eid
in: path
description: The id of the element in which to perform the operation.
required: true
schema:
type: string
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTBExportModelParams'
responses:
default:
description: default response
content:
application/octet-stream:
schema:
type: object
application/json;charset=UTF-8; qs=0.09:
schema:
type: object
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/d/{did}/{wv}/{wvid}/insertables:
get:
tags:
- Document
summary: Retrieve insertables by document ID and workspace or version ID.
operationId: getInsertables
parameters:
- name: did
in: path
required: true
schema:
type: string
- name: wv
in: path
required: true
schema:
type: string
- name: wvid
in: path
required: true
schema:
type: string
- name: elementId
in: query
schema:
type: string
- name: configuration
in: query
schema:
type: string
- name: linkDocumentId
in: query
description: Id of document that links to the document being accessed. This may provide additional access rights to the document. Allowed only with version (v) path parameter.
schema:
type: string
- name: includeParts
in: query
schema:
type: boolean
default: false
- name: includeSurfaces
in: query
schema:
type: boolean
default: false
- name: includeSketches
in: query
schema:
type: boolean
default: false
- name: includeReferenceFeatures
in: query
schema:
type: boolean
default: false
- name: includeAssemblies
in: query
schema:
type: boolean
default: false
- name: includeFeatureStudios
in: query
schema:
type: boolean
default: false
- name: includeBlobs
in: query
schema:
type: boolean
default: false
- name: allowedBlobMimeTypes
in: query
schema:
type: string
default: ''
- name: excludeNewerFSVersions
in: query
schema:
type: boolean
default: false
- name: maxFeatureScriptVersion
in: query
schema:
type: integer
format: int32
- name: includePartStudios
in: query
schema:
type: boolean
default: false
- name: includeFeatures
in: query
schema:
type: boolean
default: false
- name: includeMeshes
in: query
schema:
type: boolean
default: false
- name: includeWires
in: query
schema:
type: boolean
default: false
- name: includeFlattenedBodies
in: query
schema:
type: boolean
default: false
- name: includeApplications
in: query
schema:
type: boolean
default: false
- name: allowedApplicationMimeTypes
in: query
schema:
type: string
default: ''
- name: includeCompositeParts
in: query
schema:
type: boolean
default: false
- name: includeFSTables
in: query
schema:
type: boolean
default: false
- name: includeFSComputedPartPropertyFunctions
in: query
schema:
type: boolean
default: false
- name: includeVariables
in: query
schema:
type: boolean
default: false
- name: includeVariableStudios
in: query
schema:
type: boolean
default: false
- name: allowedBlobExtensions
in: query
schema:
type: string
default: ''
- name: isObsoletion
in: query
schema:
type: boolean
default: false
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTInsertablesListResponse'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/search:
post:
tags:
- Document
summary: Search document.
description: This returns list of documents based on search parameters.
operationId: search
requestBody:
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTDocumentSearchParams'
required: true
responses:
default:
description: default response
content:
application/json;charset=UTF-8; qs=0.09:
schema:
type: object
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
/documents/{did}:
get:
tags:
- Document
summary: Retrieve document by document ID.
operationId: getDocument
parameters:
- name: did
in: path
required: true
schema:
type: string
responses:
'200':
description: Success!
content:
application/json;charset=UTF-8; qs=0.09:
schema:
$ref: '#/components/schemas/BTDocumentInfo'
deprecated: false
security:
- OAuth2:
- OAuth2Read
BasicAuth:
- OAuth2Read
x-BTVisibility: PRODUCTION
post:
tags:
- Document
summary: Update document attributes by documen
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/onshape/refs/heads/main/openapi/onshape-document-api-openapi.yml