API v1 exposes bounded resource DTOs and explicit domain commands. It does not mirror TeamGrid’s MongoDB documents or offer a generic DDP mutation interface. Fields absent from the OpenAPI schema are private even if a similarly named value exists inside the TeamGrid application.
Current resource surface
| Resource family | Public behavior | Important boundary |
|---|---|---|
| Workspace and users | Read | Workspace, region, cell, and membership remain credential-scoped |
| Projects | List, get, create, update, complete, reopen, archive, restore | Lifecycle actions are asynchronous and require projects:lifecycle |
| Tasks | List, get, create, update, duplicate, move, replace checklist, archive, restore, complete, reopen, timer start and stop | Workflow writes use task revisions; timer commands require both tasks:write and time-entries:write |
| Time entries | List, get, create, update, archive, restore, start and stop task timers | Billed entries are immutable; billing operations and financial rates remain outside the core workflow |
| Contacts | List, get, create, update | Reads include contact relationships and non-financial CRM summaries; no public archive operation in the current contract |
| Call notes | List, get, create, archive, restore | Public content is plain text; internal rich-text storage is never returned |
| Contact groups | List, get, create, update, archive, restore | Parent changes are validated against cycles and hierarchy limits |
| Lists, services, and tags | List, get, create, update, archive, restore | Service responses can include billing rates |
| Custom-field definitions | List, get, create, update, archive, restore | Only canonical public schema metadata is writable |
| Custom-field values | Get one or 1–100 in an ordered batch, compare-and-set, compare-and-clear | Requires a strong revision for writes and every target/reference scope used by a read |
| Appointments and absences | Bounded list, get, create, compare-and-set update, archive, restore | Foreign-user access requires a delegated or administrative overlay plus product authorization |
| Availability | Bounded read | Requires an explicit IANA time zone; foreign users require delegated access |
| Comments and activity | Target-scoped collaboration | Also requires the matching contact, project, or task read scope |
| Documents and files | Document lifecycle, file metadata, private transfer intents | Signed transfer capabilities are short-lived and never exposed to MCP |
| Workspace administration | Members, invitations, roles, groups | PII is an additional overlay; mutations preserve workspace invariants and strong revisions |
| Search and exports | Bounded federated search and asynchronous CSV exports | Each requested domain is independently authorized; export download capabilities are header-only |
| Automations and integrations | Public action catalog, versioned definitions, runs, redacted installation status | Internal tasks and provider secrets remain private |
| Project templates | List, get, create, update, archive, restore, instantiate | Snapshot content stays private; instantiation is asynchronous and credential-owned |
| Planned work | List bounded windows, get task schedule, replace task schedule | Sensitive workload data; replacement is asynchronous, idempotent, and compare-and-set |
| Products | List, get, create, update, archive | purchasePrice requires finance scopes; no restore operation is currently public |
| Product groups | List, get, create, update, archive | Parent changes are hierarchy-validated; no restore operation is currently public |
| Project statements | List, get, create, update, archive, restore | Budget data and purchasePrice are finance-gated; internal order and rollup fields stay private |
| Audit events | List | Security-sensitive; intended for investigation and governance workflows |
| Webhooks | List, get, create, remove | Creation returns the signing secret once |
| Webhook deliveries | List and get | Read-only, credential-owned, privacy-reduced history |
The capability coverage ledger separately records what is released in stable 1.0, planned for a later release, or intentionally private.
Project reads include stable list and scheduling order, creation and duplication provenance, planning boundaries, last activity, and non-financial task progress counts. The owning App cell projects only these safe summary fields from its internal calculation object; costs, revenue, profit, budgets, time totals, names cached for UI rendering, and image internals are rejected at the API boundary. Project sharing is exposed separately through a full-replacement, human-principal-only contract with strong concurrency control.
Time-entry reads expose task, user and service references, creator/updater provenance, duration, billable and billed state, billing timestamp, and whether a timer is still active. Lists can filter by these safe operational fields and by a start-time window. Internal hourly rates, cost rates, financial aggregates, cached billing details, and call records are rejected at the App and API boundaries. Creating and editing completed entries, archiving/restoring them, starting/stopping task timers, and marking entries billed or unbilled form the released workflow. Billing mutations remain separate from ordinary time-entry updates, require their dedicated billing scope, and preserve the immutability rules for billed entries.
Contact reads include person/company identity, addresses, communication channels, websites, social profiles, parent/group/company relationships, provenance, last activity, and non-financial task, project, and employee counts. Lists support exact type, category, customer, group, company, parent, and creator filters. Billing configuration, rates, costs, revenue, profit, budgets, time aggregates, cached display names, image-storage internals, and embedded custom-field storage are never returned. Custom-field values remain available only through their dedicated revisioned endpoints.
Project, task, and project-template responses include developer revision fields. Their 17 mutations
require a strong If-Match precondition; another 31 operations retain resource-specific
compare-and-set contracts. See resource concurrency for the exact
boundary.
Task descriptions additionally expose descriptionFormat. Legacy and unmarked content is
normalized to plain-text; only content explicitly marked markdown-v1 is interpreted as
Markdown. The marker is preserved by task duplication and project-template instantiation. See
task description formats before
importing or rewriting descriptions.
Project lifecycle operations
Project completion, reopen, archive, and restore can cascade across related TeamGrid state. The API therefore returns a project-lifecycle operation instead of pretending that the work completed during the initiating request.
- Read the project and send the lifecycle command with its latest ETag and a stable idempotency key.
- Persist the returned operation ID, action, and target project ID.
- Treat the accepted operation as the authoritative handle for subsequent polling.
- Poll
GET /v1/project-lifecycle-operations/{id}until it reaches a terminal state, or use the SDK or CLI wait helper. - Treat a transport timeout as an unknown outcome and resume by operation ID; do not create an unrelated replacement operation.
The accepted operation exposes sourceRevision; a successful terminal operation exposes
resultRevision. Re-read the project if the next step needs its complete resulting state.
The CLI project commands accept --wait, --max-wait, and --poll-interval. The SDK exposes the
operation through projectLifecycleOperations.get() and projectLifecycleOperations.wait(). Pass
the mutation result as acceptedOperation when waiting so every poll remains bound to the accepted
operation ID, action, and project. CLI --wait does this automatically.
Finance overlays
Base and finance scopes are intentionally separate.
products:readreturns catalog data withoutpurchasePrice.products:finance:readrevealspurchasePriceonly whenproducts:readis also present.- Supplying
purchasePriceon a product create or update requires bothproducts:writeandproducts:finance:write. project-statements:readreturns non-budget statements withoutpurchasePrice.project-statements:finance:readadditionally permits budget statements and revealspurchasePricewhen the base read scope is present.- Supplying
purchasePriceon a statement create or update requires bothproject-statements:writeandproject-statements:finance:write.
The finance scopes do not reveal internal orders, carts, workflow bookkeeping, budget rollups, or provider data. Those fields are not part of the public DTO.
Credential-owned delivery history
webhooks:read permits a credential to list or get only webhook deliveries owned by that same
credential. Workspace membership alone is not enough, and deleting a webhook does not transfer its
history to another credential.
Delivery records expose bounded operational metadata: event, resource ID, state, timestamps, HTTP status, sanitized transport code, and attempt count. They never expose destination URLs, request or response bodies, payloads, headers, signing secrets, tenant routing fields, or retention internals. History is operational and retained for a bounded period; consumers must not treat it as an event archive or replay source.
Custom-field compatibility
Definition responses identify canonical writable definitions separately from unsupported or
read-only legacy shapes. Unfiltered reads can surface legacy definitions for inventory purposes.
Create and update operations accept only the canonical field and target types described by OpenAPI,
and the configuration discriminator must match fieldType.
Value operations are separate from definition operations. They expose canonical values only for contacts, projects, project journal entries, and tasks, and require strong compare-and-set revisions. See custom fields before writing values.