REST API Client

Updated on Sep 2nd, 2026,

43 views 14 min , 19 sec read 0

Overview

The REST API Client lets you connect an external application — such as an automation script, CI/CD pipeline, or integration service — to Nimble’s project-level resources using the Nimble REST API. It uses OAuth 2.0 client credentials, so the application authenticates on its own with no user login required at run time.

When you register a REST API Client, Nimble generates a Client ID and a Client Secret. You use these credentials to get a short-lived access token, then include it on every API request.

Base URL: https://api.digite.com/rest/v2

Skip Ahead to:

Get an Access Token

Testing Your API Calls

Scripts & Client Libraries

Workspaces

Forms

Instances (Workitems)

Actor Object (User vs Client)

Register a REST API Client

Go to Account Space > Administration > REST API Client.

Click REGISTER.
Enter a Client Name and an optional Description. The Client ID is auto-generated (editable before saving).

Expand Workspace Access Permissions and tick the operations — Read Card, Create Card, Update Card, Close Card, Delete Card — for each workspace this client needs access to.

Click REGISTER CLIENT. Copy the Client Secret immediately — it is shown only once and cannot be retrieved again.

Click DONE. The client appears in the list with edit and delete options.

Get an Access Token

Why exchange credentials for a token?

Every API call requires Authorization: Bearer <token>. Using a short-lived token instead of sending your secret on every request provides these security benefits:

Short-lived exposure — your secret is sent once; only the token (~1 hr) travels with each request. If intercepted, it becomes useless after expiry.
Scoped access — the token carries only the permissions needed for the session.
Revocability — a compromised token can be invalidated without rotating your client secret.
Auditability — token issuance is a logged event.
Stateless validation — downstream services verify the self-contained JWT without storing your secret.

Step — Get a Token

Do this once, then reuse the token until it expires (approximately 1 hour).

POST https://auth.digite.com/rest/v1/oauth/token

Headers

Content-Type: application/json

Body · Raw · JSON

{
  "grant_type":    "client_credentials",
  "client_id":     "nmb_cli_xxxxxxxxxxxxxxxxxxxxxxxx",
  "client_secret": "your_client_secret_here"
}

Response 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type":   "Bearer",
  "expires_in":   3600
}

Use the access_token value as Authorization: Bearer <access_token> in all subsequent requests.

Testing Your API Calls

Note: You can use any API client, HTTP tool, or IDE plugin to test and explore the Nimble REST API. The steps below use Postman as an example, but the same variables and headers apply equally to tools such as Insomnia, cURL, or any HTTP library.

If you use Postman, create an Environment with these three variables:

token — paste the access_token from the step above
baseUrl — https://api.digite.com/rest/v2
workspaceId — your workspace ID (get it from GET /workspaces)

Set these as default headers on your Postman collection (right-click collection > Edit > Headers):

Authorization: Bearer {{token}}
X-WorkspaceId: {{workspaceId}}

Scripts & Client Libraries

The examples below use Python, Node.js, and Java. You can use any language or HTTP library that supports JSON requests and custom headers.

Python (requests)

import requests

base_url     = "https://api.digite.com/rest/v2"
token        = "eyJhbGciOiJSUzI1NiIs..."   # Bearer token from Step above
workspace_id = "2110769"

headers = {
    "Authorization": f"Bearer {token}",
    "X-WorkspaceId": workspace_id,
    "Content-Type":  "application/json",
}

# List workitems
resp = requests.get(f"{base_url}/instances", headers=headers, params={"formId": "523440", "limit": 20})
for item in resp.json()["items"]:
    print(item["instanceId"], item.get("Name"))

# Create a workitem
resp = requests.post(f"{base_url}/instances", headers=headers, json={
    "formId": "523440", "Name": "Login page broken", "Priority": "High"
})
print("Created:", resp.json()["instanceId"])

Node.js (fetch)

const baseUrl     = "https://api.digite.com/rest/v2";
const token       = "eyJhbGciOiJSUzI1NiIs...";
const workspaceId = "2110769";
const headers = {
  "Authorization": `Bearer ${token}`,
  "X-WorkspaceId": workspaceId,
  "Content-Type":  "application/json",
};

// List workitems
const res = await fetch(`${baseUrl}/instances?formId=523440&limit=20`, { headers });
const data = await res.json();
data.items.forEach(item => console.log(item.instanceId, item.Name));

// Create a workitem
const res2 = await fetch(`${baseUrl}/instances`, {
  method: "POST", headers,
  body: JSON.stringify({ formId: "523440", Name: "Login page broken", Priority: "High" }),
});
console.log("Created:", (await res2.json()).instanceId);

Java (HttpClient)

import java.net.URI;
import java.net.http.*;

String baseUrl = "https://api.digite.com/rest/v2";
String token   = "eyJhbGciOiJSUzI1NiIs...";
String wsId    = "2110769";
HttpClient client = HttpClient.newHttpClient();

HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(baseUrl + "/instances?formId=523440&limit=20"))
    .header("Authorization", "Bearer " + token)
    .header("X-WorkspaceId", wsId)
    .GET().build();
HttpResponse resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

A client SDK (nimblework-finch) is planned but not yet published. Until then, use the HTTP libraries above.

Workspaces

Workspace endpoints do not require the X-WorkspaceId header.

GET — List Workspaces

GET https://api.digite.com/rest/v2/workspaces

Headers

Authorization: Bearer <access_token>
accept: application/json

Query Parameters

limit — optional — Number of results per page (default 50)
pageToken — optional — Cursor from previous response for next page
sort — optional — Field to sort by
order — optional — asc or desc

Response 200 OK

{
  "items": [{
    "workspaceId": "2110769",
    "name": "My First Project",
    "description": "FromProjectCreate",
    "createdBy": { "actorId": "353147453", "name": "Utkarsh Singh", "type": "USER" },
    "modifiedBy": { "actorId": "353147453", "name": "Utkarsh Singh", "type": "USER" },
    "createdAt": "2026-08-14T17:12:17Z"
  }],
  "total": 1,
  "pageToken": null
}

GET — Single Workspace

GET https://api.digite.com/rest/v2/workspaces/:workspaceId

Headers

Authorization: Bearer <access_token>
accept: application/json

Path Variables

workspaceId — required — e.g. 2110769

Response 200 OK

{
  "workspaceId": "2110769",
  "name": "My First Project",
  "description": "FromProjectCreate",
  "createdBy": { "actorId": "353147453", "name": "Utkarsh Singh", "type": "USER" },
  "modifiedBy": { "actorId": "353147453", "name": "Utkarsh Singh", "type": "USER" },
  "createdAt": "2026-08-14T17:12:17Z",
  "updatedAt": "2026-08-14T17:12:17Z"
}

Forms

Forms are the templates that define the fields for workitems. Every workitem belongs to a form. The X-WorkspaceId header is required for both form endpoints.

GET — List Forms

GET https://api.digite.com/rest/v2/forms

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Response 200 OK

{
  "items": [{
    "formId": "523440",
    "name": "Issue",
    "prefix": "ISS",
    "workspaceId": "2110769",
    "hexColorCode": "#FF5733",
    "custom": true,
    "createdAt": "2026-01-10T09:00:00Z",
    "fields": [
      { "fieldUniqueName": "Name",     "custom": false, "readOnly": false },
      { "fieldUniqueName": "Priority", "custom": true,  "readOnly": false },
      { "fieldUniqueName": "Status",   "custom": false, "readOnly": true  }
    ]
  }]
}

GET — Single Form (with full field schema)

GET https://api.digite.com/rest/v2/forms/:formId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

formId — required — Numeric form ID, e.g. 523440

Response 200 OK

{
  "formId": "523440",
  "name": "Issue",
  "prefix": "ISS",
  "workspaceId": "2110769",
  "fields": [
    { "fieldUniqueName": "Name",     "custom": false, "readOnly": false, "type": "TEXT",   "required": true  },
    { "fieldUniqueName": "Priority", "custom": true,  "readOnly": false, "type": "LOOKUP", "required": false }
  ]
}

Use this to discover valid field names and types before writing instances.

Instances (Workitems)

An instance is a single workitem (card). Custom field values are sent and received at the root level alongside system fields. Always include formId in the request body for writes.

GET — List Instances

GET https://api.digite.com/rest/v2/instances

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Query Parameters

formId — optional — Filter by form, e.g. 523440
expand — optional — true — inlines lookup field values
limit — optional — Max results per page
pageToken — optional — Cursor for next page
sort — optional — Field name to sort by
order — optional — asc or desc

Response 200 OK

{
  "items": [{
    "instanceId": "523440-42",
    "id": "ISS-42",
    "formId": "523440",
    "workspaceId": "2110769",
    "Name": "Login page broken",
    "Priority": "High",
    "Status": "Open",
    "createdBy": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
    "modifiedBy": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
    "createdAt": "2026-08-01T10:00:00Z"
  }],
  "total": 1
}

GET — Single Instance

GET https://api.digite.com/rest/v2/instances/:instanceId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Use the instanceId returned by POST (e.g. 523440-42), not the business key (ISS-42)

Query Parameters

expand — optional — true — inlines lookup field values

Response 200 OK

{
  "instanceId": "523440-42",
  "id": "ISS-42",
  "formId": "523440",
  "workspaceId": "2110769",
  "Name": "Login page broken",
  "Priority": "High",
  "Status": "Open",
  "flags": [],
  "blocks": [],
  "createdBy": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
  "modifiedBy": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
  "createdAt": "2026-08-01T10:00:00Z"
}

Actor Object — `createdBy` / `modifiedBy` (User vs Client)

Every response that includes createdBy and modifiedBy returns an actor object. Its shape tells you whether a human user or a registered API client performed the action.

The fields present depend on the actor type:

"USER" — actorId, name, type
"CLIENT" — userId (in nmb_cli_… format), name, type, and onBehalfOf

When a human user performs the action, the actor object looks like this:

"createdBy": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" }

When a registered API client performs the action, the actor is the client itself. The onBehalfOf object identifies the user account whose access the client is using:

"createdBy": {
  "name": "Claude AI",
  "type": "CLIENT",
  "userId": "nmb_cli_b1c0def41481a874498be77d",
  "onBehalfOf": {
    "name": "Simple Workflow",
    "type": "USER",
    "userId": "353135992"
  }
}

How to read it: userId (in nmb_cli_… format) is the API client that made the request, and onBehalfOf is the user account it acted for. This lets you audit both the client and the underlying user for every action taken through the REST API.

Response Example — Created by an API Client

A workitem created by an API client returns both createdBy and modifiedBy as CLIENT actor objects:

{
  "instanceId": "823666",
  "id": "ACTY1",
  "formId": "412162",
  "workspaceId": "412160",
  "Name": "Testing Activity card",
  "Status": "Open",
  "version": 1,
  "flags": [],
  "blocks": [],
  "createdBy": {
    "name": "Claude AI",
    "type": "CLIENT",
    "userId": "nmb_cli_b1c0def41481a874498be77d",
    "onBehalfOf": { "name": "Simple Workflow", "type": "USER", "userId": "353135992" }
  },
  "modifiedBy": {
    "name": "Claude AI",
    "type": "CLIENT",
    "userId": "nmb_cli_b1c0def41481a874498be77d",
    "onBehalfOf": { "name": "Simple Workflow", "type": "USER", "userId": "353135992" }
  },
  "createdAt": "2026-08-26T09:12:02Z",
  "updatedAt": "2026-08-26T09:12:02Z"
}

GET — Subblocks (child workitems)

GET https://api.digite.com/rest/v2/instances/:instanceId/subblocks

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Parent workitem instance ID

Query Parameters

depth — required — 0 = direct children only · -1 = full tree · n = n levels deep

Response 200 OK

{
  "subblocks": [{
    "instanceId": "523440-43",
    "formId": "523441",
    "workspaceId": "2110769",
    "data": { "Name": "Sub-task A", "Status": "Open" },
    "subblocks": []
  }]
}

POST — Create Instance

POST https://api.digite.com/rest/v2/instances

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json
accept: application/json

Body · Raw · JSON

{
  "formId":          "412162",
  "Name":            "Login page broken",
  "Description":     "Reproduce: open Chrome, go to /login, click Submit without credentials.",
  "Priority":        "High",
  "EstimateHours":   4,
  "PercentComplete": 0,
  "DueDate":         "2026-09-15T00:00:00.000Z",
  "Tags":            ["bug", "login"]
}

formId is the only required body field. Custom field names must match exactly what GET /forms/{formId} returns. workspaceId is NOT sent in the body — it comes from the X-WorkspaceId header.

Response 201 Created

{ "instanceId": "523440-42", "id": "ISS-42" }

The Location response header also contains the URL of the new instance.

PUT — Full Replace

PUT https://api.digite.com/rest/v2/instances/:instanceId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json
accept: application/json

Path Variables

instanceId — required — e.g. 523440-42

Body · Raw · JSON

{
  "formId":          "412162",
  "Name":            "Login page broken — updated",
  "Description":     "Full replacement via PUT.",
  "Priority":        "Critical",
  "EstimateHours":   8,
  "PercentComplete": 0,
  "DueDate":         "2026-09-15T00:00:00.000Z"
}

Important: This is a full replacement — any custom field not included in the body is cleared. System fields (Status, flags, blocks) are never cleared by PUT. Cleared fields do not appear in the response.

Response 200 OK

{
  "formId": "412162",
  "instanceId": "836334",
  "version": 0,
  "workspaceId": "412417",
  "Name": "Login page broken — updated",
  "Description": "Full replacement via PUT.",
  "Priority": "Critical",
  "EstimateHours": 8,
  "PercentComplete": 0,
  "DueDate": "2026-09-15T00:00:00.000+00:00"
}

PATCH — Partial Update

PATCH https://api.digite.com/rest/v2/instances/:instanceId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json
accept: application/json

Path Variables

instanceId — required — e.g. 523440-42

Body · Raw · JSON

{
  "formId":          "412162",
  "Name":            "Login page broken",
  "PercentComplete": 40,
  "Priority":        "High",
  "DueDate":         "2026-09-15T00:00:00.000Z"
}

Only the fields you send are updated — all other fields remain untouched. formId is required. Do not send flag or block keys here — use the dedicated sub-resource endpoints.

Response 200 OK

{
  "formId": "412162",
  "instanceId": "836334",
  "version": 0,
  "workspaceId": "412417",
  "Name": "Login page broken",
  "PercentComplete": 40,
  "Priority": "High",
  "DueDate": "2026-09-15T00:00:00.000+00:00"
}

DELETE — Delete Instance

DELETE https://api.digite.com/rest/v2/instances/:instanceId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — e.g. 523440-42

Response 200 OK

{ "success": true }

Returns 404 if the instance has already been deleted.

Flags

Available on standalone form types only. Returns 400 for sub-block instances.

POST — Flag an Instance

POST https://api.digite.com/rest/v2/instances/:instanceId/flags

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Instance to flag

Body · Raw · JSON

{ "comment": "Needs immediate attention" }

comment is required (max 5,000 characters). To get the actionId for unflagging, call GET /instances/{instanceId} and look at the flags field.

Response 200 OK

{
  "instanceId": "308785",
  "formId": "524430",
  "workspaceId": "524321",
  "version": 2,
  "deleted": false,
  "createdBy": "353136425",
  "modifiedBy": "353136425",
  "createdAt": "2026-02-25T04:14:51Z",
  "updatedAt": "2026-08-19T10:00:00Z",
  "Name": "MSSQL Jar Upgrade",
  "Status": "Open",
  "Priority": "1044"
}

Returns the full updated instance.

DELETE — Unflag an Instance

DELETE https://api.digite.com/rest/v2/instances/:instanceId/flags/:actionId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Instance to unflag
actionId — required — The actionId from the flag entry, e.g. flag_001

Body · Raw · JSON

{ "comment": "Resolved" }

comment is required. Returns 400 (not 409) for: no flag history, actionId mismatch, or already unflagged.

Response 200 OK

{
  "instanceId": "308785",
  "formId": "524430",
  "workspaceId": "524321",
  "version": 3,
  "deleted": false,
  "createdBy": "353136425",
  "modifiedBy": "353136425",
  "createdAt": "2026-02-25T04:14:51Z",
  "updatedAt": "2026-08-19T10:05:00Z",
  "Name": "MSSQL Jar Upgrade",
  "Status": "Open",
  "Priority": "1044"
}

Blocks

POST — Block an Instance

POST https://api.digite.com/rest/v2/instances/:instanceId/blocks

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Instance to block

Body · Raw · JSON

{
  "reason":  "Waiting for design approval",
  "comment": "Blocked until design sign-off is received"
}

Both reason and comment are required. Returns 400 if either is absent. Use GET /forms/{formId} to discover valid blocking reasons. To get the actionId for unblocking, call GET /instances/{instanceId} and look at the blocks field.

Response 200 OK

{
  "instanceId": "308785",
  "formId": "524430",
  "workspaceId": "524321",
  "version": 2,
  "deleted": false,
  "createdBy": "353136425",
  "modifiedBy": "353136425",
  "createdAt": "2026-02-25T04:14:51Z",
  "updatedAt": "2026-08-19T10:00:00Z",
  "Name": "MSSQL Jar Upgrade",
  "Status": "Open",
  "Priority": "1044"
}

Returns the full updated instance.

DELETE — Unblock an Instance

DELETE https://api.digite.com/rest/v2/instances/:instanceId/blocks/:actionId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Instance to unblock
actionId — required — The actionId from the block entry

Body · Raw · JSON

{ "comment": "Design approved, unblocking" }

comment is required — returns 400 if absent or blank.

Response 200 OK

{
  "instanceId": "308785",
  "formId": "524430",
  "workspaceId": "524321",
  "version": 3,
  "deleted": false,
  "createdBy": "353136425",
  "modifiedBy": "353136425",
  "createdAt": "2026-02-25T04:14:51Z",
  "updatedAt": "2026-08-19T10:05:00Z",
  "Name": "MSSQL Jar Upgrade",
  "Status": "Open",
  "Priority": "1044"
}

Votes

POST — Vote on an Instance

POST https://api.digite.com/rest/v2/instances/:instanceId/votes

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Instance to vote on

No body required. Returns 409 if you have already voted on this instance.

Response 200 OK

{
  "instanceId": "308785",
  "formId": "524430",
  "workspaceId": "524321",
  "version": 2,
  "deleted": false,
  "createdBy": "353136425",
  "modifiedBy": "353136425",
  "createdAt": "2026-02-25T04:14:51Z",
  "updatedAt": "2026-08-19T10:00:00Z",
  "Name": "MSSQL Jar Upgrade",
  "Status": "Open",
  "Priority": "1044"
}

Returns the full updated instance.

DELETE — Remove Vote

DELETE https://api.digite.com/rest/v2/instances/:instanceId/votes

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — Instance to remove vote from

Returns 409 if you have not voted on this instance.

Response 200 OK

{
  "instanceId": "308785",
  "formId": "524430",
  "workspaceId": "524321",
  "version": 3,
  "deleted": false,
  "createdBy": "353136425",
  "modifiedBy": "353136425",
  "createdAt": "2026-02-25T04:14:51Z",
  "updatedAt": "2026-08-19T10:05:00Z",
  "Name": "MSSQL Jar Upgrade",
  "Status": "Open",
  "Priority": "1044"
}

Returns the full updated instance.

Links

Creates or removes a typed directional link between two instances. HIERARCHY links also set parentCard on the source instance.

PUT — Create a Link

PUT https://api.digite.com/rest/v2/instances/:instanceId/link

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Source instance

Body · Raw · JSON

{
  "to": {
    "workItemId":  "ISS-50",
    "formId":      "523440",
    "workSpaceId": "2110769"
  },
  "relationInverse": "fulfills",
  "metaType": "DEPENDENCY"
}

metaType values: HIERARCHY (default), DEPENDENCY, TRACEBAILITY, CONTAINMENT, ASSOCIATION.

Response 200 OK

{
  "id": "lnk_001",
  "from": { "workItemId": "523440-42", "formId": "523440", "workSpaceId": "2110769" },
  "to":   { "workItemId": "523440-50", "formId": "523440", "workSpaceId": "2110769" },
  "metaType": "DEPENDENCY",
  "relation": "depends on",
  "relationInverse": "fulfills",
  "workSpaceId": "2110769"
}

DELETE — Remove a Link

DELETE https://api.digite.com/rest/v2/instances/:instanceId/link/:targetId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — Source instance
targetId — required — Target instance ID

Query Parameters

metaType — optional — Must match the value used when the link was created. Defaults to HIERARCHY.

Response 200 OK

{
  "id": "lnk_001",
  "from": { "workItemId": "523440-42", "formId": "523440", "workSpaceId": "2110769" },
  "to":   { "workItemId": "523440-50", "formId": "523440", "workSpaceId": "2110769" },
  "metaType": "DEPENDENCY",
  "relation": "depends on",
  "relationInverse": "fulfills",
  "workSpaceId": "2110769"
}

Comments

Limitations: User mentions (@user), emoji, and inline attachments are not supported in comment text. Use POST /attachments to attach files.

POST — Add a Comment

POST https://api.digite.com/rest/v2/instances/:instanceId/comments

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Instance to comment on

Body · Raw · JSON

{ "content": "Reproduced on Chrome 126. Stack trace attached.", "type": "COMMENT" }

content is required (min 1 char). type is optional, defaults to COMMENT.

Response 201 Created

{ "commentId": "cmt_abc123" }

GET — List Comments

GET https://api.digite.com/rest/v2/instances/:instanceId/comments

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Instance to list comments for

The response key is content, not comments.

Response 200 OK

{
  "content": [{
    "commentId": "cmt_abc123",
    "content": "Reproduced on Chrome 126.",
    "type": "COMMENT",
    "authorId": "353136425",
    "actor": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
    "workitemId": "523440-42",
    "workspaceId": "2110769",
    "createdAt": "2026-08-19T10:05:00Z"
  }]
}

GET — Single Comment

GET https://api.digite.com/rest/v2/instances/:instanceId/comments/:commentId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Parent instance
commentId — required — e.g. cmt_abc123

The replies array is always empty here — replies are stored as independent comments at the same level. Use GET list to retrieve all comments including replies.

Response 200 OK

{
  "commentId": "cmt_abc123",
  "content": "Reproduced on Chrome 126.",
  "authorId": "353136425",
  "actor": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
  "workitemId": "523440-42",
  "type": "COMMENT",
  "replies": []
}

PUT — Add a Reply

PUT https://api.digite.com/rest/v2/instances/:instanceId/comments/:commentId/replies

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Parent instance
commentId — required — Comment to reply to

Body · Raw · JSON

{ "content": "Also reproduced on Safari 17." }

No response body. The reply is stored as a separate independent comment at the same level.

PUT — Edit Comment Text

PUT https://api.digite.com/rest/v2/instances/:instanceId/comments/:commentId/content

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Parent instance
commentId — required — Comment to edit

Body · Raw · JSON

{ "content": "Reproduced on Chrome 126 and Edge 124. Stack trace attached." }

Response 200 OK

{ "commentId": "cmt_abc123", "updated": true }

DELETE — Delete Comment

DELETE https://api.digite.com/rest/v2/instances/:instanceId/comments/:commentId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — Parent instance
commentId — required — Comment to delete

Empty body on success.

Attachments

POST — Upload a File

POST https://api.digite.com/rest/v2/instances/:instanceId/attachments

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: Do NOT set manually — set automatically for multipart/form-data

Path Variables

instanceId — required — Instance to attach to

Body · form-data: key file, type File, value: file to upload (max 32 MB). In Postman: Body → form-data → key file → change type from Text to File → Select Files.

Response 201 Created

{ "attachmentId": "att_789012" }

POST — Link an External Resource

POST https://api.digite.com/rest/v2/instances/:instanceId/attachments/link

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Instance to attach to

Body · Raw · JSON

{
  "attachmentName": "Design Mockup",
  "content":        "https://figma.com/file/abc123",
  "linkedUsing":    "Figma"
}

Response 201 Created

{ "attachmentId": "att_link_001" }

GET — List Attachments

GET https://api.digite.com/rest/v2/instances/:instanceId/attachments

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Instance to list attachments for

The response key is content, not attachments.

Response 200 OK

{
  "content": [{
    "attachmentId": "att_789012",
    "name": "screenshot.png",
    "mimeType": "image/png",
    "fileSize": 204800,
    "workitemId": "523440-42",
    "workspaceId": "2110769",
    "isLink": false,
    "uploaderId": "353136425",
    "actor": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
    "createdAt": "2026-08-19T11:00:00Z"
  }]
}

DELETE — Delete Attachment

DELETE https://api.digite.com/rest/v2/instances/:instanceId/attachments/:attachmentId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — Parent instance
attachmentId — required — Attachment to delete

Empty body on success.

Todos

GET — List Todos

GET https://api.digite.com/rest/v2/instances/:instanceId/todos

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Parent instance

Query Parameters

assigneeId — optional — Filter by assignee user ID
limit — optional — Max results per page
pageToken — optional — Cursor for next page

Response 200 OK

{
  "items": [{
    "todoId": "TODO1",
    "workspaceId": "2110769",
    "formId": "523440",
    "workitemId": "523440-42",
    "name": "Write unit tests",
    "status": "Open",
    "isTimeLogged": false,
    "assigneeId": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
    "createdBy":  { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
    "updatedBy":  { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
    "estimate": 4,
    "remaining": 4,
    "position": 1
  }]
}

GET — Single Todo

GET https://api.digite.com/rest/v2/instances/:instanceId/todos/:todoId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Parent instance
todoId — required — e.g. TODO1

Response 200 OK

{
  "todoId": "TODO1",
  "workspaceId": "2110769",
  "formId": "523440",
  "workitemId": "523440-42",
  "name": "Write unit tests",
  "status": "Open",
  "isTimeLogged": false,
  "assigneeId": { "actorId": "353136425", "name": "Utkarsh Singh", "type": "USER" },
  "estimate": 4,
  "remaining": 4,
  "position": 1
}

POST — Create a Todo

POST https://api.digite.com/rest/v2/instances/:instanceId/todos

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Parent instance

Body · Raw · JSON

{
  "name":       "Write unit tests",
  "assigneeId": "353136425",
  "estimate":   4,
  "position":   1
}

name is required. assigneeId, estimate (≥ 0), and position (≥ 1) are optional. Returns 404 if the parent instance does not exist.

Response 201 Created

{ "todoId": "TODO1" }

PATCH — Update a Todo

PATCH https://api.digite.com/rest/v2/instances/:instanceId/todos/:todoId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Parent instance
todoId — required — Todo to update

Body · Raw · JSON

{ "estimate": 6 }

All fields optional: name, assigneeId, estimate. Only sent fields are updated.

Response 200 OK

{ "todoId": "TODO1" }

POST — Close a Todo

POST https://api.digite.com/rest/v2/instances/:instanceId/todos/:todoId/close

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — Parent instance
todoId — required — Todo to close

No body required.

Response 200 OK

{ "todoId": "TODO1", "status": "closed", "actualFinish": "2026-08-19T12:00:00Z" }

POST — Reopen a Todo

POST https://api.digite.com/rest/v2/instances/:instanceId/todos/:todoId/reopen

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — Parent instance
todoId — required — Todo to reopen

No body required.

Response 200 OK

{ "todoId": "TODO1", "status": "open" }

DELETE — Delete a Todo

DELETE https://api.digite.com/rest/v2/instances/:instanceId/todos/:todoId

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>

Path Variables

instanceId — required — Parent instance
todoId — required — Todo to delete

Response 200 OK

{ "message": "deleted" }

Time Entries

Time entries are keyed by todoId + date. Submitting the same pair again overwrites the existing entry.

POST — Log Time

POST https://api.digite.com/rest/v2/instances/:instanceId/todos/:todoId/timeentries/:date

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
Content-Type: application/json

Path Variables

instanceId — required — Parent instance
todoId — required — Todo to log time against
date — required — Format YYYY-MM-DD — cannot be a future date

Body · Raw · JSON

{ "actual": 3.5, "remaining": 0.5 }

actual is required (hours logged). remaining and estimate are optional.

Response 201 Created

{
  "actual": 3.5,
  "remaining": 0.5,
  "latestRemaining": 0.5,
  "totalActual": 7.0,
  "timesheetDate": "2026-08-19T00:00:00.000Z"
}

GET — Get Time Entry for a Date

GET https://api.digite.com/rest/v2/instances/:instanceId/todos/:todoId/timeentries/:date

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Path Variables

instanceId — required — Parent instance
todoId — required — Todo ID
date — required — Date in YYYY-MM-DD format

Returns 404 if no entry exists for that todo + date combination. timesheetDate in the response is a plain date string (YYYY-MM-DD).

Response 200 OK

{
  "workspaceId": "2110769",
  "workItemId": "UST-42",
  "todoId": "TODO1",
  "timesheetUserId": "353136425",
  "actual": 3.5,
  "remaining": 0.5,
  "isRemainingUpdated": true,
  "timesheetDate": "2026-08-19",
  "createdAt": "2026-08-19T10:30:00.000Z",
  "updatedAt": "2026-08-19T10:30:00.000Z"
}

GET — List Time Entries by Date Range

GET https://api.digite.com/rest/v2/timeentries

Headers

Authorization: Bearer <access_token>
X-WorkspaceId: <workspace_id>
accept: application/json

Query Parameters

timesheetStartDate — required — YYYY-MM-DD
timesheetEndDate — required — YYYY-MM-DD
workspaceIds[] — optional — Repeatable — filter by workspace
limit — optional — 1–100, default 50
pageToken — optional — Cursor for next page

nextPageToken is omitted when there are no further pages. Pass it as the pageToken query param to fetch the next page.

Response 200 OK

{
  "items": [{
    "workspaceId": "2110769",
    "workItemId": "UST-42",
    "todoId": "TODO1",
    "timesheetUserId": "353136425",
    "actual": 3.5,
    "remaining": 0.5,
    "isRemainingUpdated": true,
    "timesheetDate": "2026-08-19",
    "createdAt": "2026-08-19T10:30:00.000Z",
    "updatedAt": "2026-08-19T10:30:00.000Z"
  }],
  "nextPageToken": "eyJsYXN0SWQiOiI2NjlmYWRkYzQ3NWYwNzVjYWEwM2Y4ZTYifQ=="
}

Important Points

A REST API Client operates as its own independent identity — actions are attributed to the client, not to the user who registered it.
The Client Secret is displayed only once at registration. If you lose it, regenerate it from the listing.
Grant each client only the workspace permissions it needs.
Tokens expire after approximately 1 hour. Cache and reuse; request a new one only when expired.
workspaceId is passed via the X-WorkspaceId header — never in the request body.
formId is required in every instance write request (POST, PUT, PATCH).
Custom field names must match exactly what GET /forms/{formId} returns.
PUT is a full replacement — any custom field not included is cleared. Use PATCH for partial updates.
Flag and block actionId values are obtained by calling GET /instances/{instanceId} and reading the flags or blocks field.
Always use HTTPS.

Was this helpful?
Yes No

Overview

Register a REST API Client

Get an Access Token

Why exchange credentials for a token?

Step — Get a Token

Testing Your API Calls

Scripts & Client Libraries

Python (requests)

Node.js (fetch)

Java (HttpClient)

Workspaces

GET — List Workspaces

GET — Single Workspace

Forms

GET — List Forms

GET — Single Form (with full field schema)

Instances (Workitems)

GET — List Instances

GET — Single Instance

Actor Object — createdBy / modifiedBy (User vs Client)

Response Example — Created by an API Client

GET — Subblocks (child workitems)

POST — Create Instance

PUT — Full Replace

PATCH — Partial Update

DELETE — Delete Instance

Flags

POST — Flag an Instance

DELETE — Unflag an Instance

Blocks

POST — Block an Instance

DELETE — Unblock an Instance

Votes

POST — Vote on an Instance

DELETE — Remove Vote

Links

PUT — Create a Link

DELETE — Remove a Link

Comments

POST — Add a Comment

GET — List Comments

GET — Single Comment

PUT — Add a Reply

PUT — Edit Comment Text

DELETE — Delete Comment

Attachments

POST — Upload a File

POST — Link an External Resource

GET — List Attachments

DELETE — Delete Attachment

Todos

GET — List Todos

GET — Single Todo

POST — Create a Todo

PATCH — Update a Todo

POST — Close a Todo

POST — Reopen a Todo

DELETE — Delete a Todo

Time Entries

POST — Log Time

GET — Get Time Entry for a Date

GET — List Time Entries by Date Range

Important Points

Actor Object — `createdBy` / `modifiedBy` (User vs Client)