Workspace API Procedures

Use these procedures to manage projects and workspace users.

All use POST https://api.diggle.com/procedure/{procedureName}, a Workspace API Bearer key and a JSON body envelope.

createProject

Creates a project in the selected workspace.

Endpoint

POST /procedure/createProject

Request

{
  "body": {
    "workspaceId": "<workspace-id>",
    "name": "Training"
  }
}

Parameters

Response

"<project-id>"

Behavior

Returns the new project identifier as a JSON string. The authenticated key must have workspace edit authority. Each successful call creates a new project, even when the name already exists.

Errors

Errors from this procedure are plain text. Current validation and access-denied errors generally return HTTP 500; they do not consistently use 400, 401 or 403. Correct the input or credential before retrying. See API & SCIM Errors

deleteProject

Archives a project by default. An explicit force option requests permanent deletion.

Endpoint

POST /procedure/deleteProject

Request

{
  "body": {
    "projectId": "<project-id>"
  }
}

Parameters

Response

HTTP 200 with no response body on success. Do not require a JSON result.

Behavior

Requires edit authority for the project. The default operation archives the project, folders and Diggles and removes explicit project user grants. With force: true, the project and its content are deleted. Do not use permanent deletion for user offboarding; use revokeWorkspaceUserAccess.

Errors

Errors from this procedure are plain text. Current validation and access-denied errors generally return HTTP 500; they do not consistently use 400, 401 or 403. Correct the input or credential before retrying. See API & SCIM Errors.

Notes

Do not assume deletion is an atomic or safely repeatable operation after a connection failure. Check the project’s state before retrying.

upsertWorkspaceUser

Creates a new account when eligible, or manages workspace access for an existing account. The request below includes an initial name for a new account; omit fullName when updating existing access.

Endpoint

POST /procedure/upsertWorkspaceUser

Request

{
  "body": {
    "workspaceId": "<workspace-id>",
    "email": "[email protected]",
    "fullName": "Example Trainer",
    "role": "creator",
    "projects": [
      "<project-id>"
    ]
  }
}

Parameters

Response

"<user-id>"

Behavior

Returns the canonical Diggle user ID as a JSON string. Requires workspace administrator authority. Repeated equivalent requests reconcile the same user instead of creating duplicates. Project IDs are deduplicated; every supplied project must belong to the workspace. Retained existing project grants keep their existing project role; newly added grants use the selected workspace role.

Qualifying workspace enrollment grants Enterprise access and reconciles personal paid billing. An ordinary upsert cannot override a SCIM local block or source-inactive enrollment. Workspace API project assignment is separate from SCIM; SCIM does not provision project access.

Errors

Changing an existing global account name returns HTTP 403 with Workspace access updates cannot change existing global account profiles. Errors from this procedure are plain text. Current validation and access-denied errors generally return HTTP 500; they do not consistently use 400, 401 or 403. Correct the input or credential before retrying. See API & SCIM Errors.

Notes

To clear a local administrative veto without restoring access, send only workspaceId, email and clearLocalBlock: true. Then let the designated SCIM source send active=true. No workspace membership or historical project access is restored by unblock alone.

{
  "body": {
    "workspaceId": "<workspace-id>",
    "email": "[email protected]",
    "clearLocalBlock": true
  }
}

Note: This API cannot change an existing global full name. SCIM displayName belongs to the provisioning-source profile and does not generally change the global account either.

getWorkspaceUsers

Lists users in a workspace.

Endpoint

POST /procedure/getWorkspaceUsers

Request

{
  "body": {
    "workspaceId": "<workspace-id>"
  }
}

Parameters

Response

HTTP 200 with a JSON array; an empty result is []. Selected integration fields are shown below; additional fields may be present.

[
  {
    "user_id": "<user-id>",
    "name": "Example Trainer",
    "email": "[email protected]",
    "workspace_role": "creator",
    "status": "registered"
  }
]

Behavior

With a Workspace API key, this procedure requires current workspace administrator authority. Results are ordered by full name. user_id is the canonical Diggle ID required by revokeWorkspaceUserAccess. workspace_role is the membership role; do not substitute a global account role or the computed status.

Pending invitations may appear as workspace_role: "pending" and pending: true; this does not mean active workspace access. This procedure has no pagination parameters.

Errors

Errors from this procedure are plain text. Current validation and access-denied errors generally return HTTP 500; they do not consistently use 400, 401 or 403. Correct the input or credential before retrying. See API & SCIM Errors.

Include projects

Set withProjects to true to include a projects array on each returned user.

{
  "body": {
    "workspaceId": "<workspace-id>",
    "withProjects": true
  }
}

Selected response fields:

[
  {
    "user_id": "<user-id>",
    "workspace_role": "creator",
    "projects": [
      { "project_id": "<project-id>" }
    ]
  }
]

The array includes explicit project grants and shared workspace projects. Additional fields may be present and differ between entries. Use project_id to identify projects; deduplicate by that ID if needed. Do not treat every entry as an explicit private-project grant.

getWorkspaceUser

Looks up a user in a workspace by email.

Endpoint

POST /procedure/getWorkspaceUser

Request

{
  "body": {
    "workspaceId": "<workspace-id>",
    "email": "[email protected]"
  }
}

Parameters

Response

HTTP 200 with a user object, or JSON null if no matching workspace membership is found. Selected fields:

{
  "user_id": "<user-id>",
  "email": "[email protected]",
  "full_name": "Example Trainer",
  "deactivated": false
}

Behavior

Requires workspace administrator authority. The returned user_id identifies the global Diggle account; it is not the SCIM User resource ID. Use the exact email returned by getWorkspaceUsers when possible. This response does not return a workspace_role field; use the list procedure for that.

Errors

Errors from this procedure are plain text. Current validation and access-denied errors generally return HTTP 500; they do not consistently use 400, 401 or 403. Correct the input or credential before retrying. See API & SCIM Errors.

revokeWorkspaceUserAccess

Revokes access to the selected workspace without deleting the global Diggle account.

Endpoint

POST /procedure/revokeWorkspaceUserAccess

Request

{
  "body": {
    "workspaceId": "<workspace-id>",
    "userId": "<user-id>"
  }
}

Parameters

Response

HTTP 200:

{
  "workspaceId": "<workspace-id>",
  "userId": "<user-id>",
  "access": "revoked"
}

Behavior

Requires a Workspace API key with current administrator authority for the same workspace. A key from another workspace cannot perform this operation. It removes the selected workspace membership, invitations and applicable project grants. It retains the global Diggle account, login and SSO identities, personal content and unrelated workspaces. Project content itself is not deleted.

Another qualifying Enterprise workspace keeps Enterprise access. When an ordinary user loses the final qualifying Enterprise workspace, the account becomes Free. Previously cancelled personal paid access is not restored. Removing only a pending invitation does not cancel an otherwise valid personal paid plan.

For a SCIM-managed user, this is a local administrative veto. Later SCIM active=true cannot silently restore access. Use the separate unblock action documented in upsertWorkspaceUser; then the designated source may explicitly reactivate the user.

Errors

Errors are plain text. Example: workspaceId must be a non-empty stable identifier.

Notes

Idempotent: repeating the call after the relationship is absent returns the same revoked representation. This does not reveal whether an unrelated global account exists. If you revoke the membership carrying the calling key, that key cannot authenticate subsequent requests. The last-admin protection still applies.

Related articles

• Workspace API: Getting Started
• Workspace API Authentication
• API & SCIM Errors