Project templates

Project templates capture a reusable project, list, and task structure. Public responses contain only bounded template metadata: title, description, color, source project ID, archive state, snapshot version, timestamps, and list/task counts. The captured snapshot, actors, workspace routing, and generated documents are never returned.

Reads require project-templates:read; create, update, archive, and restore require project-templates:write. Instantiation and its status resource require both project-templates:write and projects:write because the operation creates a project and child resources.

Capture and instantiate

Creating a template requires a stable Idempotency-Key because TeamGrid captures the current source project. Instantiation also requires its own key:

teamgrid project-templates create \
  --data '{"color":"#1557ed","projectId":"PROJECT_ID","title":"Delivery"}' \
  --idempotency-key template-delivery-v1 --output json

teamgrid project-templates instantiate TEMPLATE_ID \
  --data '{"name":"Customer rollout"}' \
  --idempotency-key customer-rollout-42 --wait --output json

The HTTP instantiation response is 202 Accepted, includes Location, and returns a credential-owned projectTemplateInstantiation resource. Poll that exact location or use the SDK wait helper. Terminal states are succeeded and failed; pending/running responses never imply that generated resources are complete.

const accepted = await client.projectTemplates.instantiate(
  templateId,
  { name: 'Customer rollout', dueAt: '2026-08-31T23:59:59.999Z' },
  {
    idempotencyKey: 'customer-rollout-42',
  },
)
const completed = await client.projectTemplateInstantiations.wait(accepted.data.id, {
  acceptedOperation: accepted.data,
  maxWaitMs: 120_000,
})

Passing acceptedOperation binds every poll to the accepted operation ID and template and generated project IDs. The SDK rejects a response if any of those immutable fields changes while polling. The CLI applies the same binding automatically when --wait is present.

Only the credential that created an instantiation can read its operation status. A replay with the same idempotency key, payload, and source revision returns the original operation; using the key for different input returns 409. Templates expose developer revisions; accepted and terminal operations expose their source and result revisions. The 1.2.2 MCP server includes template metadata, instantiation and operation status in projects-write and full. Accepted work must be followed through its status tool; acceptance is not proof of completed project creation.