Workspace (Public API)

Get and update workspace settings. Scoped to the API key’s workspace. GET returns id, name, rootFolderId, archiveFolderId (use archiveFolderId with GET /items/:id/items to list archived items). Placeholder: Update and branding/whitelabelling are not yet implemented.

Get workspace

GET /api/v2/workspace

Returns the workspace for the API key (id, name, rootFolderId, archiveFolderId). Use archiveFolderId with GET /items/:id/items to list archived items.

curl "https://api.markup.io/api/v2/workspace" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" 

{
  "data": {
    "id": "some id",
    "name": "some name",
    "rootFolderId": "some rootFolderId"
  }
}

Response Body - WorkspaceResponse

List workspaces

GET /api/v2/workspaces

List all workspaces in the API key’s organization. Only organization-scoped API keys can call this; workspace-scoped keys receive 403. Cursor-based pagination: use since to fetch the next page, before for the previous. Sort is client-controlled via sortBy (name | lastActivity) and dir (asc | desc). Default order is name ascending, page size 50.

curl "https://api.markup.io/api/v2/workspaces" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" 

{
  "data": {
    "data": [
      {
        "id": "some id",
        "name": "some name",
        "rootFolderId": "some rootFolderId"
      }
    ],
    "hasMore": true
  }
}

Response Body ListWorkspacesResponse

Create workspace

POST /api/v2/workspace

Create a new workspace in the API key’s organization. Only organization-scoped API keys can call this; workspace-scoped keys receive 403. Body: name (required). Returns 201 with WorkspaceResponse (id, name, rootFolderId, archiveFolderId).

curl "https://api.markup.io/api/v2/workspace" \
    -X POST \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{
    "name": "My New Workspace"
}'

{
  "data": {
    "id": "some id",
    "name": "some name",
    "rootFolderId": "some rootFolderId"
  }
}

Response Body - WorkspaceResponse

Request Body CreateWorkspacePublicRequest

Update workspace

PATCH /api/v2/workspace

Update workspace name and/or slug. Pass workspaceId in query/body for org-scoped keys. Body: { name?: string, slug?: string }. At least one required. Returns 200 with WorkspaceResponse.

curl "https://api.markup.io/api/v2/workspace" \
    -X PATCH \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{}'

{
  "data": {
    "id": "some id",
    "name": "some name",
    "rootFolderId": "some rootFolderId"
  }
}

Response Body - WorkspaceResponse

Request Body UpdateWorkspacePublicRequest

Delete workspace

DELETE /api/v2/workspace

Delete a workspace. Organization-scoped API keys can delete any workspace in the org (pass workspaceId in query or body). Workspace-scoped API keys can delete only the workspace they manage (no workspaceId needed). Returns 204 on success.

curl "https://api.markup.io/api/v2/workspace" \
    -X DELETE \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" 

204 No Content

Get storage settings

GET /api/v2/workspace/settings

Returns the workspace’s original-file storage policy (STORE_ALWAYS | NEVER_STORE | ASK_PER_PROJECT). Pass workspaceId in query for org-scoped keys.

curl "https://api.markup.io/api/v2/workspace/settings" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" 

{
  "data": {
    "originalFileStoragePolicy": "NEVER_STORE"
  }
}

Response Body - WorkspaceSettingsPublicResponse

Update storage settings

PATCH /api/v2/workspace/settings

Update the workspace’s original-file storage policy. Set applyToExisting: true together with originalFileStoragePolicy: "NEVER_STORE" to also archive originals already retained in the workspace; the response then includes appliedToExistingCount. Requires the workspace to have the storage feature enabled. Pass workspaceId in query/body for org-scoped keys.

curl "https://api.markup.io/api/v2/workspace/settings" \
    -X PATCH \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" \
	--data '{
    "originalFileStoragePolicy": "NEVER_STORE",
    "applyToExisting": true
}'

{
  "data": {
    "originalFileStoragePolicy": "NEVER_STORE"
  }
}

Response Body - WorkspaceSettingsPublicResponse

Request Body UpdateWorkspaceSettingsBodyRequest

Archive all retained originals

POST /api/v2/workspace/originals/archive-all

Archives every retained original file in the workspace and returns the number archived ({ archivedCount }). Requires the workspace to have the storage feature enabled.

curl "https://api.markup.io/api/v2/workspace/originals/archive-all" \
    -X POST \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" 

204 No Content

Get storage breakdown

GET /api/v2/workspace/storage-breakdown

Returns a per-bucket storage breakdown for the workspace’s organization (pdfs, videos, images, attachments, originals, total, in bytes). Requires the workspace to have the storage feature enabled.

curl "https://api.markup.io/api/v2/workspace/storage-breakdown" \
    -X GET \
    -H "Authorization: Bearer <API-KEY-SECRET>" \
    -H "Markup-API-Version: 2023-02-22" \
    -H "Content-Type: application/json" 

{
  "data": {
    "pdfs": 123,
    "videos": 123,
    "images": 123,
    "attachments": 123,
    "originals": 123,
    "total": 123
  }
}

Response Body - IStorageBreakdown

Related types

WorkspaceResponse

WorkspaceSettingsPublicResponse

OriginalFileStoragePolicy

WorkspaceResponse

IStorageBreakdown