{"id":24095,"date":"2026-08-21T14:06:55","date_gmt":"2026-08-21T08:36:55","guid":{"rendered":"https:\/\/www.nimblework.com\/knowledge-base\/nimble\/?post_type=article&p=24095"},"modified":"2026-08-24T09:40:55","modified_gmt":"2026-08-24T04:10:55","slug":"nimble-rest-api-reference-guide","status":"publish","type":"article","link":"https:\/\/www.nimblework.com\/knowledge-base\/nimble\/article\/nimble-rest-api-reference-guide\/","title":{"rendered":"Nimble REST API Reference Guide"},"content":{"rendered":"

Overview<\/h2>\n

The Nimble REST API lets you interact with your workspace programmatically \u2014 create and update workitems, manage todos, log time, add comments, and more. This guide covers every available endpoint with example requests and responses for use with Postman.<\/p>\n

Base URL:<\/strong> https:\/\/api.nimblework.com\/blox\/openapi<\/code><\/p>\n

Getting a Token<\/h2>\n

Every API call requires Authorization: Bearer <token><\/code>. Register a client once, then request a new token whenever your token expires (~1 hour).<\/p>\n

Step 1 \u2014 Register an API Client in Nimble<\/h3>\n
    \n
  1. Log in to your Nimble instance.<\/li>\n
  2. In the left sidebar, click Account Space<\/strong>.<\/li>\n
  3. In the top nav, click Administration<\/strong> \u2192 REST API Client<\/strong>.<\/li>\n
  4. Click + REGISTER<\/strong> (top right).<\/li>\n
  5. Enter a Client Name<\/strong>. The Client ID<\/strong> is auto-generated \u2014 copy it.<\/li>\n
  6. Expand Workspace Access Permissions<\/strong> and tick the permissions you need (Read Card, Create Card, Update Card, etc.).<\/li>\n
  7. Click REGISTER CLIENT<\/strong>. Copy the Client Secret<\/strong> \u2014 it is shown only once<\/strong>. Click DONE<\/strong>.<\/li>\n<\/ol>\n

    Step 2 \u2014 Get a Token<\/h3>\n

    POST<\/strong> https:\/\/api.nimblework.com\/rest\/v1\/oauth\/token<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

    Body \u00b7 raw \u00b7 JSON<\/strong><\/p>\n

    {\r\n  \"grant_type\": \"client_credentials\",\r\n  \"client_id\": \"nmb_cli_xxxxxxxxxxxx\",\r\n  \"client_secret\": \"your_client_secret_here\"\r\n}<\/code><\/pre>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...\",\r\n  \"token_type\": \"Bearer\",\r\n  \"expires_in\": 3600\r\n}<\/code><\/pre>\n
    Copy the access_token<\/code>. Use it as Bearer <access_token><\/code> in all subsequent requests.<\/p>\n
    Postman Setup<\/h2>\n
    Create a Postman Environment with these variables so you only set them once:<\/p>\n\n\n\n\n\n\n\n\n
    Variable<\/th>\nExample value<\/th>\n<\/tr>\n<\/thead>\n
    token<\/td>\neyJhbGciOiJSUzI1NiIs\u2026 (paste from Step 2)<\/td>\n<\/tr>\n
    baseUrl<\/td>\nhttps:\/\/api.nimblework.com\/blox\/openapi<\/td>\n<\/tr>\n
    workspaceId<\/td>\n2110769<\/td>\n<\/tr>\n
    correlation<\/td>\nINSTANCE:accountId:userId<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Then in every request use {{baseUrl}}<\/code>, {{token}}<\/code>, etc.<\/p>\n
    Workspaces<\/h2>\n
    GET \u2014 List Workspaces<\/h3>\n
    GET<\/strong> {{baseUrl}}\/workspaces?limit=10<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n\n\n\n
    Param<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    limit<\/td>\nopt<\/td>\nNumber of results per page (default 50)<\/td>\n<\/tr>\n
    pageToken<\/td>\nopt<\/td>\nCursor from previous response for next page<\/td>\n<\/tr>\n
    sort<\/td>\nopt<\/td>\nField to sort by<\/td>\n<\/tr>\n
    order<\/td>\nopt<\/td>\nasc or desc<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"items\": [\r\n    {\r\n      \"workspaceId\": \"2110769\",\r\n      \"name\": \"My First Project\",\r\n      \"description\": \"FromProjectCreate\",\r\n      \"createdBy\": \"353147453\",\r\n      \"modifiedBy\": \"353147453\",\r\n      \"createdAt\": \"2026-08-14T17:12:17Z\"\r\n    }\r\n  ],\r\n  \"total\": 1,\r\n  \"pageToken\": null\r\n}<\/code><\/pre>\n
    GET \u2014 Single Workspace<\/h3>\n
    GET<\/strong> {{baseUrl}}\/workspaces\/:workspaceId<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n
    Path Variable<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    workspaceId<\/td>\nreq<\/td>\ne.g. 2110769<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"workspaceId\": \"2110769\",\r\n  \"name\": \"My First Project\",\r\n  \"description\": \"FromProjectCreate\",\r\n  \"createdBy\": \"353147453\",\r\n  \"modifiedBy\": \"353147453\",\r\n  \"createdAt\": \"2026-08-14T17:12:17Z\",\r\n  \"updatedAt\": \"2026-08-14T17:12:17Z\"\r\n}<\/code><\/pre>\n
    Forms<\/h2>\n
    Forms are the templates that define the fields for instances (workitems). Every instance belongs to a form. The X-WorkspaceId<\/code> header is required for both form endpoints.<\/p>\n
    GET \u2014 List Forms<\/h3>\n
    GET<\/strong> {{baseUrl}}\/forms<\/code><\/p>\n\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    X-WorkspaceId<\/td>\n{{workspaceId}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"items\": [\r\n    {\r\n      \"formId\": \"523440\",\r\n      \"name\": \"Issue\",\r\n      \"prefix\": \"ISS\",\r\n      \"workspaceId\": \"2110769\",\r\n      \"hexColorCode\": \"#FF5733\",\r\n      \"custom\": true,\r\n      \"createdAt\": \"2026-01-10T09:00:00Z\",\r\n      \"fields\": [\r\n        { \"fieldUniqueName\": \"Name\",        \"custom\": false, \"readOnly\": false },\r\n        { \"fieldUniqueName\": \"Priority\",     \"custom\": true,  \"readOnly\": false },\r\n        { \"fieldUniqueName\": \"Assigned To\",  \"custom\": true,  \"readOnly\": false },\r\n        { \"fieldUniqueName\": \"Status\",       \"custom\": false, \"readOnly\": true  }\r\n      ]\r\n    }\r\n  ]\r\n}<\/code><\/pre>\n
    GET \u2014 Single Form (with full field schema)<\/h3>\n
    GET<\/strong> {{baseUrl}}\/forms\/:formId<\/code><\/p>\n\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    X-WorkspaceId<\/td>\n{{workspaceId}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n
    Path Variable<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    formId<\/td>\nreq<\/td>\nNumeric form ID, e.g. 523440<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"formId\": \"523440\",\r\n  \"name\": \"Issue\",\r\n  \"prefix\": \"ISS\",\r\n  \"workspaceId\": \"2110769\",\r\n  \"fields\": [\r\n    {\r\n      \"fieldUniqueName\": \"Name\",\r\n      \"custom\": false,\r\n      \"readOnly\": false,\r\n      \"type\": \"TEXT\",\r\n      \"required\": true\r\n    },\r\n    {\r\n      \"fieldUniqueName\": \"Priority\",\r\n      \"custom\": true,\r\n      \"readOnly\": false,\r\n      \"type\": \"LOOKUP\",\r\n      \"required\": false\r\n    }\r\n  ]\r\n}<\/code><\/pre>\n
    Instances (Workitems)<\/h2>\n
    An instance is a single workitem (card). Custom field values are sent and received at the root level alongside system fields. Always include formId<\/code> in the request body for writes.<\/p>\n
    GET \u2014 List Instances<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances?workspaceId={{workspaceId}}&formId=523440&limit=20<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n\n\n\n\n\n\n
    Param<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    workspaceId<\/td>\nreq<\/td>\nYour workspace ID<\/td>\n<\/tr>\n
    formId<\/td>\nopt<\/td>\nFilter by form, e.g. 523440<\/td>\n<\/tr>\n
    expand<\/td>\nopt<\/td>\ntrue \u2014 inlines lookup field values<\/td>\n<\/tr>\n
    limit<\/td>\nopt<\/td>\nMax results per page<\/td>\n<\/tr>\n
    pageToken<\/td>\nopt<\/td>\nCursor for next page<\/td>\n<\/tr>\n
    sort<\/td>\nopt<\/td>\nField name to sort by<\/td>\n<\/tr>\n
    order<\/td>\nopt<\/td>\nasc or desc<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"items\": [\r\n    {\r\n      \"instanceId\": \"523440-42\",\r\n      \"id\": \"ISS-42\",\r\n      \"formId\": \"523440\",\r\n      \"workspaceId\": \"2110769\",\r\n      \"Name\": \"Login page broken\",\r\n      \"Priority\": \"High\",\r\n      \"Status\": \"Open\",\r\n      \"createdAt\": \"2026-08-01T10:00:00Z\"\r\n    }\r\n  ],\r\n  \"total\": 1\r\n}<\/code><\/pre>\n
    GET \u2014 Single Instance<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances\/:instanceId?expand=true<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n
    Path Variable<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    instanceId<\/td>\nreq<\/td>\ne.g. ISS-42<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"instanceId\": \"523440-42\",\r\n  \"id\": \"ISS-42\",\r\n  \"formId\": \"523440\",\r\n  \"workspaceId\": \"2110769\",\r\n  \"Name\": \"Login page broken\",\r\n  \"Priority\": \"High\",\r\n  \"Status\": \"Open\",\r\n  \"flags\": [],\r\n  \"blocks\": [],\r\n  \"createdAt\": \"2026-08-01T10:00:00Z\"\r\n}<\/code><\/pre>\n
    GET \u2014 Subblocks (child instances)<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances\/:instanceId\/subblocks?depth=-1<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n
    Param<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    depth<\/td>\nreq<\/td>\n0 = direct children only \u00b7 -1 = full tree \u00b7 n = n levels<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"items\": [\r\n    { \"instanceId\": \"523440-43\", \"id\": \"ISS-43\", \"Name\": \"Sub-task A\", \"...\": \"...\" }\r\n  ]\r\n}<\/code><\/pre>\n
    POST \u2014 Create Instance<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances<\/code><\/p>\n\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"formId\": \"523440\",\r\n  \"workspaceId\": \"2110769\",\r\n  \"Name\": \"Login page broken\",\r\n  \"Priority\": \"High\",\r\n  \"Assigned To\": \"John Smith\"\r\n}<\/code><\/pre>\n
    Note:<\/strong> formId<\/code> and workspaceId<\/code> are required. All other fields are custom fields from the form schema \u2014 use the exact field names returned by GET \/forms\/:formId<\/code>.<\/p>\n
    Response 201 CREATED<\/strong><\/p>\n
    {\r\n  \"instanceId\": \"523440-42\",\r\n  \"id\": \"ISS-42\"\r\n}<\/code><\/pre>\n
    The Location<\/code> response header also contains the URL of the new instance.<\/p>\n
    PUT \u2014 Full Replace<\/h3>\n
    PUT<\/strong> {{baseUrl}}\/instances\/:instanceId<\/code><\/p>\n\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"formId\": \"523440\",\r\n  \"Name\": \"Login page broken \u2014 updated\",\r\n  \"Priority\": \"Critical\"\r\n}<\/code><\/pre>\n
    Important:<\/strong> This is a full replacement. Any custom field not included in the body (e.g. Assigned To<\/code>) will be cleared. System fields like Status<\/code>, flags<\/code>, and blocks<\/code> are never cleared by PUT.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"instanceId\": \"523440-42\",\r\n  \"id\": \"ISS-42\",\r\n  \"Name\": \"Login page broken \u2014 updated\",\r\n  \"Priority\": \"Critical\",\r\n  \"Assigned To\": null\r\n}<\/code><\/pre>\n
    PATCH \u2014 Partial Update<\/h3>\n
    PATCH<\/strong> {{baseUrl}}\/instances\/:instanceId<\/code><\/p>\n\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"formId\": \"523440\",\r\n  \"Priority\": \"Low\"\r\n}<\/code><\/pre>\n
    Note:<\/strong> Only Priority<\/code> changes. All other fields remain untouched. formId<\/code> is required. Do not send flag or block keys here \u2014 use the dedicated sub-resource endpoints.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"instanceId\": \"523440-42\",\r\n  \"id\": \"ISS-42\",\r\n  \"Priority\": \"Low\"\r\n}<\/code><\/pre>\n
    DELETE \u2014 Delete Instance<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 204 NO CONTENT<\/strong> \u2014 Empty body. Returns 404 if the instance has already been deleted.<\/p>\n
    Flags<\/h2>\n
    Only available on instances of STANDALONE form types. Returns 400 for sub-block instances.<\/p>\n
    POST \u2014 Flag an Instance<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/flags<\/code><\/p>\n\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n
    accept<\/td>\n*\/*<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"comment\": \"Needs immediate attention\"\r\n}<\/code><\/pre>\n
    comment<\/code> is optional. Max 5,000 characters if provided.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"instanceId\": \"523440-42\",\r\n  \"flags\": [\r\n    {\r\n      \"actionId\": \"flag_001\",\r\n      \"actor\": { \"actorId\": \"353136425\", \"type\": \"USER\", \"name\": \"John Smith\" },\r\n      \"comment\": \"Needs immediate attention\",\r\n      \"createdAt\": \"2026-08-19T10:00:00Z\"\r\n    }\r\n  ]\r\n}<\/code><\/pre>\n
    DELETE \u2014 Unflag an Instance<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId\/flags\/:actionId<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n
    Path Variable<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    actionId<\/td>\nreq<\/td>\nThe actionId from the flag entry, e.g. flag_001<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Body \u00b7 raw \u00b7 JSON (optional)<\/strong><\/p>\n
    {\r\n  \"comment\": \"Resolved\"\r\n}<\/code><\/pre>\n
    Returns 400 (not 409) for error cases: no flag history, actionId mismatch, already unflagged.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    { \"instanceId\": \"523440-42\", \"flags\": [] }<\/code><\/pre>\n
    Blocks<\/h2>\n
    POST \u2014 Block an Instance<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/blocks<\/code><\/p>\n\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n
    accept<\/td>\n*\/*<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"reason\": \"Waiting for design approval\",\r\n  \"comment\": \"Blocked until design sign-off is received\"\r\n}<\/code><\/pre>\n
    Both reason<\/code> and comment<\/code> are required. Returns 400 if either is absent or blank. Use GET \/forms\/:formId<\/code> to discover valid blocking reasons for the form.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"instanceId\": \"523440-42\",\r\n  \"blocks\": [\r\n    {\r\n      \"actionId\": \"block_001\",\r\n      \"reason\": \"Waiting for design approval\",\r\n      \"comment\": \"Blocked until design sign-off is received\",\r\n      \"actor\": { \"actorId\": \"353136425\", \"type\": \"USER\", \"name\": \"John Smith\" }\r\n    }\r\n  ]\r\n}<\/code><\/pre>\n
    DELETE \u2014 Unblock an Instance<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId\/blocks\/:actionId<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"comment\": \"Design approved, unblocking\"\r\n}<\/code><\/pre>\n
    comment<\/code> is required \u2014 returns 400 if absent or blank.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    { \"instanceId\": \"523440-42\", \"blocks\": [] }<\/code><\/pre>\n
    Votes<\/h2>\n
    POST \u2014 Vote on an Instance<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/votes<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    No body required. Returns 409 if you have already voted on this instance.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    { \"instanceId\": \"523440-42\", \"action\": \"voted\", \"votes\": 1 }<\/code><\/pre>\n
    DELETE \u2014 Remove Vote<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId\/votes<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Returns 409 if you have not voted on this instance.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    { \"instanceId\": \"523440-42\", \"action\": \"unvoted\", \"votes\": 0 }<\/code><\/pre>\n
    Links<\/h2>\n
    Creates or removes a typed directional link between two instances. HIERARCHY links also set parentCard<\/code> on the source instance.<\/p>\n
    PUT \u2014 Create a Link<\/h3>\n
    PUT<\/strong> {{baseUrl}}\/instances\/:instanceId\/link<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"to\": {\r\n    \"workItemId\": \"ISS-50\",\r\n    \"formId\": \"523440\",\r\n    \"workSpaceId\": \"2110769\"\r\n  },\r\n  \"relationInverse\": \"fulfills\",\r\n  \"metaType\": \"DEPENDENCY\"\r\n}<\/code><\/pre>\n
    metaType values:<\/strong> HIERARCHY (default), DEPENDENCY, TRACEBAILITY, CONTAINMENT, ASSOCIATION.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    { \"linkId\": \"lnk_001\", \"from\": \"ISS-42\", \"to\": \"ISS-50\", \"metaType\": \"DEPENDENCY\" }<\/code><\/pre>\n
    DELETE \u2014 Remove a Link<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId\/link\/:targetId?metaType=DEPENDENCY<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n
    Query Param<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    metaType<\/td>\nopt<\/td>\nMust match the value used when the link was created. Defaults to HIERARCHY.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    { \"linkId\": \"lnk_001\", \"removed\": true }<\/code><\/pre>\n
    Comments<\/h2>\n
    Limitations:<\/strong> User mentions (@user), emoji, and inline attachments are not supported in comment text. Use POST \/attachments to attach files to an instance.<\/p>\n
    POST \u2014 Add a Comment<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/comments<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"content\": \"Reproduced on Chrome 126. Stack trace attached.\",\r\n  \"type\": \"COMMENT\"\r\n}<\/code><\/pre>\n
    content<\/code> is required (min 1 char). type<\/code> is optional, defaults to COMMENT.<\/p>\n
    Response 201 CREATED<\/strong><\/p>\n
    { \"commentId\": \"cmt_abc123\" }<\/code><\/pre>\n
    GET \u2014 List Comments<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances\/:instanceId\/comments<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"comments\": [\r\n    {\r\n      \"commentId\": \"cmt_abc123\",\r\n      \"content\": \"Reproduced on Chrome 126.\",\r\n      \"type\": \"COMMENT\",\r\n      \"authorId\": \"353136425\",\r\n      \"createdAt\": \"2026-08-19T10:05:00Z\",\r\n      \"replies\": []\r\n    }\r\n  ]\r\n}<\/code><\/pre>\n
    GET \u2014 Single Comment (with replies)<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances\/:instanceId\/comments\/:commentId<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"commentId\": \"cmt_abc123\",\r\n  \"content\": \"Reproduced on Chrome 126.\",\r\n  \"authorId\": \"353136425\",\r\n  \"replies\": [\r\n    { \"commentId\": \"cmt_def456\", \"content\": \"Also on Firefox.\", \"authorId\": \"353147453\" }\r\n  ]\r\n}<\/code><\/pre>\n
    PUT \u2014 Add a Reply<\/h3>\n
    PUT<\/strong> {{baseUrl}}\/instances\/:instanceId\/comments\/:commentId\/replies<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    { \"content\": \"Also reproduced on Safari 17.\" }<\/code><\/pre>\n
    Response 200 OK<\/strong><\/p>\n
    { \"commentId\": \"cmt_ghi789\" }<\/code><\/pre>\n
    PUT \u2014 Edit Comment Text<\/h3>\n
    PUT<\/strong> {{baseUrl}}\/instances\/:instanceId\/comments\/:commentId\/content<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    { \"content\": \"Reproduced on Chrome 126 and Edge 124. Stack trace attached.\" }<\/code><\/pre>\n
    Response 200 OK<\/strong><\/p>\n
    { \"commentId\": \"cmt_abc123\", \"updated\": true }<\/code><\/pre>\n
    DELETE \u2014 Delete Comment<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId\/comments\/:commentId<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 204 NO CONTENT<\/strong> \u2014 Empty body on success.<\/p>\n
    Attachments<\/h2>\n
    POST \u2014 Upload a File<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/attachments<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\nDo NOT set manually \u2014 Postman sets this automatically for form-data<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Body \u00b7 form-data<\/strong><\/p>\n\n\n\n\n\n
    Key<\/th>\nType<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    file<\/td>\nFile<\/td>\nSelect file from your computer (max 32 MB)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    In Postman: Body tab \u2192 select form-data<\/strong> \u2192 set key to file<\/code> \u2192 hover the key and change type from Text to File<\/strong> \u2192 click Select Files.<\/p>\n
    Response 201 CREATED<\/strong><\/p>\n
    { \"attachmentId\": \"att_789012\" }<\/code><\/pre>\n
    POST \u2014 Link an External Resource<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/attachments\/link<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"attachmentName\": \"Design Mockup\",\r\n  \"content\": \"https:\/\/figma.com\/file\/abc123\",\r\n  \"linkedUsing\": \"Figma\"\r\n}<\/code><\/pre>\n
    Response 201 CREATED<\/strong><\/p>\n
    { \"attachmentId\": \"att_link_001\" }<\/code><\/pre>\n
    GET \u2014 List Attachments<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances\/:instanceId\/attachments<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"attachments\": [\r\n    {\r\n      \"attachmentId\": \"att_789012\",\r\n      \"name\": \"screenshot.png\",\r\n      \"mimeType\": \"image\/png\",\r\n      \"fileSize\": 204800,\r\n      \"createdAt\": \"2026-08-19T11:00:00Z\"\r\n    }\r\n  ]\r\n}<\/code><\/pre>\n
    DELETE \u2014 Delete Attachment<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId\/attachments\/:attachmentId<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 204 NO CONTENT<\/strong> \u2014 Empty body on success.<\/p>\n
    Todos<\/h2>\n
    GET \u2014 List Todos<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n\n\n
    Param<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    assigneeId<\/td>\nopt<\/td>\nFilter by assignee user ID<\/td>\n<\/tr>\n
    limit<\/td>\nopt<\/td>\nMax results per page<\/td>\n<\/tr>\n
    pageToken<\/td>\nopt<\/td>\nCursor for next page<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"todos\": [\r\n    {\r\n      \"todoId\": \"TODO1\",\r\n      \"name\": \"Write unit tests\",\r\n      \"status\": \"open\",\r\n      \"assigneeId\": \"353136425\",\r\n      \"estimate\": 4\r\n    }\r\n  ]\r\n}<\/code><\/pre>\n
    POST \u2014 Create a Todo<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"name\": \"Write unit tests\",\r\n  \"assigneeId\": \"353136425\",\r\n  \"estimate\": 4,\r\n  \"formId\": \"523440\"\r\n}<\/code><\/pre>\n
    name<\/code> is required. All other fields are optional.<\/p>\n
    Response 201 CREATED<\/strong><\/p>\n
    { \"todoId\": \"TODO1\" }<\/code><\/pre>\n
    PATCH \u2014 Update a Todo<\/h3>\n
    PATCH<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos\/:todoId<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"estimate\": 6\r\n}<\/code><\/pre>\n
    All fields optional: name<\/code>, assigneeId<\/code>, estimate<\/code>. Only sent fields are updated.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    { \"todoId\": \"TODO1\", \"estimate\": 6 }<\/code><\/pre>\n
    POST \u2014 Close a Todo<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos\/:todoId\/close<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    No body required.<\/p>\n
    Response 200 OK<\/strong><\/p>\n
    { \"todoId\": \"TODO1\", \"status\": \"closed\", \"actualFinish\": \"2026-08-19T12:00:00Z\" }<\/code><\/pre>\n
    POST \u2014 Reopen a Todo<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos\/:todoId\/reopen<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    { \"todoId\": \"TODO1\", \"status\": \"open\" }<\/code><\/pre>\n
    DELETE \u2014 Delete a Todo<\/h3>\n
    DELETE<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos\/:todoId<\/code><\/p>\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    { \"message\": \"deleted\" }<\/code><\/pre>\n
    Time Entries<\/h2>\n
    Time entries are keyed by todoId<\/code> + date<\/code>. Submitting the same pair again overwrites the existing entry. Date format: YYYY-MM-DD<\/strong>.<\/p>\n
    POST \u2014 Log Time<\/h3>\n
    POST<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos\/:todoId\/timeentries\/:date<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    Content-Type<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n
    Path Variable<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    date<\/td>\nreq<\/td>\nFormat YYYY-MM-DD, e.g. 2026-08-19. Cannot be a future date.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    {\r\n  \"actual\": 3.5,\r\n  \"remaining\": 0.5\r\n}<\/code><\/pre>\n
    actual<\/code> is required (hours logged). remaining<\/code> and estimate<\/code> are optional.<\/p>\n
    Response 201 CREATED<\/strong><\/p>\n
    {\r\n  \"actual\": 3.5,\r\n  \"remaining\": 0.5,\r\n  \"latestRemaining\": 0.5,\r\n  \"totalActual\": 7.0,\r\n  \"timesheetDate\": \"2026-08-19\"\r\n}<\/code><\/pre>\n
    GET \u2014 Get Time Entry for a Date<\/h3>\n
    GET<\/strong> {{baseUrl}}\/instances\/:instanceId\/todos\/:todoId\/timeentries\/:date<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"actual\": 3.5,\r\n  \"remaining\": 0.5,\r\n  \"timesheetDate\": \"2026-08-19\"\r\n}<\/code><\/pre>\n
    Returns 404 if no entry exists for that todo + date combination.<\/p>\n
    GET \u2014 List Time Entries by Date Range<\/h3>\n
    GET<\/strong> {{baseUrl}}\/timeentries?timesheetStartDate=2026-08-01&timesheetEndDate=2026-08-19&limit=50<\/code><\/p>\n\n\n\n\n\n\n
    Header<\/th>\nValue<\/th>\n<\/tr>\n<\/thead>\n
    Authorization<\/td>\nBearer {{token}}<\/td>\n<\/tr>\n
    accept<\/td>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n\n\n\n\n\n\n\n\n\n
    Param<\/th>\nRequired<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
    timesheetStartDate<\/td>\nreq<\/td>\nYYYY-MM-DD<\/td>\n<\/tr>\n
    timesheetEndDate<\/td>\nreq<\/td>\nYYYY-MM-DD<\/td>\n<\/tr>\n
    workspaceIds[]<\/td>\nopt<\/td>\nRepeatable \u2014 filter by workspace<\/td>\n<\/tr>\n
    limit<\/td>\nopt<\/td>\n1\u2013100, default 50<\/td>\n<\/tr>\n
    pageToken<\/td>\nopt<\/td>\nCursor for next page<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
    Response 200 OK<\/strong><\/p>\n
    {\r\n  \"items\": [\r\n    {\r\n      \"todoId\": \"TODO1\",\r\n      \"instanceId\": \"523440-42\",\r\n      \"actual\": 3.5,\r\n      \"timesheetDate\": \"2026-08-19\"\r\n    }\r\n  ],\r\n  \"total\": 1\r\n}<\/code><\/pre>\n
    \n