Quickstart

This quickstart shows the shortest path from a new API token to a working TeamGrid integration.

1. Create an API Token

Open TeamGrid and go to:

Team settings -> Developer -> API tokens

Create a token for the team you want to integrate. Store the token securely. TeamGrid does not require a separate team id in API requests because the token already identifies the team.

2. Call the API

Send the token in the Authorization header:

curl https://api.teamgrid.app/teams \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

A successful GET /teams response returns the team associated with the token.

3. List Users

Users are often needed before assigning tasks or creating time entries. Use GET /users to list users in the token team.

curl https://api.teamgrid.app/users \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

You can filter by email address:

curl "https://api.teamgrid.app/[email protected]" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

4. Create a Project

Use POST /projects to create a project.

curl https://api.teamgrid.app/projects \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Website relaunch",
    "description": "Implementation project for the new website."
  }'

5. Create a Task

Use the project id returned by the project request, then create the task with POST /tasks.

curl https://api.teamgrid.app/tasks \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Prepare launch checklist",
    "projectId": "PROJECT_ID",
    "plannedTime": 120
  }'

plannedTime is expressed in minutes.

6. Start and Stop Time Tracking

Use Start task time tracking to start tracking with POST /tasks/{_id}/startTracking. Use Stop task time tracking to stop tracking with POST /tasks/{_id}/stopTracking.

curl https://api.teamgrid.app/tasks/TASK_ID/startTracking \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "USER_ID",
    "time": "2026-07-01T09:00:00Z"
  }'

curl https://api.teamgrid.app/tasks/TASK_ID/stopTracking \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "USER_ID",
    "time": "2026-07-01T10:15:00Z"
  }'