End-to-end task workflow

This tutorial reads a task, changes its name with a strong precondition, and verifies the result. Use a dedicated test task. MCP 1.2.2 can complete the reviewed write when its cell and credential satisfy the required CAS and scope gates.

Prerequisites

• a credential in the correct region with workspace:read and tasks:read;
• tasks:write for any requested update, including the explicit MCP work profile;
• one existing test task ID;
• an explicit intended new name.

Set the values without printing the credential:

export TEAMGRID_API_TOKEN='reveal-once-value'
export TEAMGRID_TASK_ID='task-id'
export TEAMGRID_TASK_NAME='Reviewed integration task'

HTTP

Read the task and retain its strong ETag response header:

curl --fail-with-body --dump-header task.headers \
  --header "Authorization: Bearer $TEAMGRID_API_TOKEN" \
  --header "Accept: application/json" \
  "https://api.de.teamgrid.app/v1/tasks/$TEAMGRID_TASK_ID"

Extract the ETag without copying it into logs, then send the guarded update:

TEAMGRID_TASK_ETAG="$(awk 'tolower($1)=="etag:" {sub(/\r$/, "", $2); print $2}' task.headers)"
curl --fail-with-body \
  --request PATCH \
  --header "Authorization: Bearer $TEAMGRID_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "If-Match: $TEAMGRID_TASK_ETAG" \
  --data "{\"name\":\"$TEAMGRID_TASK_NAME\"}" \
  "https://api.de.teamgrid.app/v1/tasks/$TEAMGRID_TASK_ID"

For customer-provided text, construct JSON with a JSON library rather than shell interpolation. A 412 means the task changed after the read; fetch it again and decide whether the new server value can be merged.

TypeScript SDK

import { TeamGridApiError, TeamGridClient } from '@teamgrid/api-client'

const client = new TeamGridClient({
  token: process.env.TEAMGRID_API_TOKEN!,
  timeoutMs: 30_000,
})

const task = await client.tasks.get(process.env.TEAMGRID_TASK_ID!)

try {
  const updated = await client.tasks.update(
    task.data.id,
    { name: process.env.TEAMGRID_TASK_NAME! },
    { ifMatch: task.transport.headers.etag },
  )
  console.log(updated.data.id, updated.data.attributes.name)
} catch (error) {
  if (error instanceof TeamGridApiError && error.status === 412) {
    throw new Error('Task changed; re-read and reconcile before retrying.')
  }
  throw error
}

The client derives the regional API endpoint from the credential and validates the returned task envelope and strong ETag.

Download the runnable example module and its pinned package manifest, save the manifest as package.json, run npm install, and then execute node teamgrid-task-workflow.mjs with the three required environment variables. Inspect both files before running them against a workspace.

CLI

teamgrid tasks get "$TEAMGRID_TASK_ID" --output json
teamgrid tasks update "$TEAMGRID_TASK_ID" \
  --data "{\"name\":\"$TEAMGRID_TASK_NAME\"}" \
  --if-match "$TEAMGRID_TASK_ETAG" \
  --output json

For automation, parse the first command’s JSON output rather than scraping table text. A stale revision exits with the documented concurrency exit code; re-read instead of repeating the same write blindly. See the exact CLI task reference.

MCP

Configure the core profile, then ask the trusted host:

Use teamgrid_task_get to read task TASK_ID. Return only its id, name, project id,
completion state, and developer revision. Do not call any other TeamGrid tool.

Review the read before allowing it. With release 1.2.2, select work, verify the access plan and current workspace, then propose a teamgrid_task_update call containing workspaceId, the task id, its fresh expectedRevision and data.name. Approve only the intended rename. Read the returned task ID again to verify the change. A revision conflict requires a fresh read; an uncertain commit requires inspection before retrying. Follow the complete MCP write walkthrough for exact quoted meta.etag handling, JSON arguments and outcome recovery. Earlier 1.2.1 packages provided only reads; install the current 1.2.2 release for writes.

Verify and clean up

Read the task again and verify the expected name and a new revision. Remove task.headers, unset the shell variables, and restore or archive the dedicated test task according to the workspace’s test-data policy. Finally, confirm the request in the API audit trail without exporting the bearer credential or payload.