GET projects

GET /api/rest/v1/teams/projects returns the projects that the API client’s team is involved with, including each project’s current status and its most recent status changes.

It is designed to be used in conjunction with the create tasks API: the id of a project and the id of one of its phases are what you pass when creating a task against a project.

GET https://thgflow.com/api/rest/v1/teams/projects

Always call the API over https://. A plain http:// request is redirected and the Authorization header is dropped on the redirect, which results in a 401.

Response

{
  "projects": Project[]
}

interface Project {
  id: string;
  team_id: string;
  code: string;                        // e.g. UNF-P12
  name: string;
  description: string;
  start_at: number | null;             // unix timestamp (seconds)
  end_at: number | null;               // unix timestamp (seconds)
  is_archived: boolean;
  coordinator: User | null;            // same shape as GET team members
  phases: ProjectPhase[];
  status: string | null;               // e.g. "Not Started", "In Progress", "On Hold", "Completed", "Cancelled"
  health: string | null;               // RAG status, e.g. "Green", "Amber", "Red"
  health_description: string | null;  // markdown entered with the current health status
  status_history: ProjectStatusChange[];
}

interface ProjectPhase {
  id: string;
  project_id: string;
  name: string;
  description: string;
  finance_status: string;
  approval_status: string;
  is_default: boolean;
}

Keys are always present in the response. start_at, end_at, coordinator, status, health and health_description are null until they have been set on the project.

Status history

status_history lists the most recent changes made to a project’s status, health or health_description, newest first. At most 5 entries are returned.

interface ProjectStatusChange {
  changed_at: number;                  // unix timestamp (seconds)
  changed_by: User | Pick<User, "id"> | null;  // who made the change; see note below
  application: string;                 // where it was changed from, e.g. "flow-ui"
  changes: {                           // only the fields changed at that moment are present
    status?: FieldChange;
    health?: FieldChange;
    health_description?: FieldChange;
  };
}

interface FieldChange {
  from: string | null;                 // value before the change, null if it was unset
  to: string | null;                   // value after the change, null if it was cleared
}

• Only the fields that were changed at that moment appear in changes. A health update made from the Flow UI typically changes health and health_description together, while a status change is usually recorded on its own.
• changed_by is the user who made the change. If that user has since been removed, the object contains only their id (the other User fields are absent). It is null only for changes with no recorded user.
• Changes made in the last few seconds may not be included yet; they are recorded asynchronously and appear shortly after.
• The history is derived from the project’s recent activity log, so a project with a very large number of other edits since its last status change may return fewer than 5 entries.

Example

{
  "projects": [
    {
      "id": "0d69e436-03ae-4a80-aa82-8a2f1187689b",
      "team_id": "23d5b52c-750e-4f3f-ab19-8feae1d59677",
      "code": "UNF-P12",
      "name": "Checkout redesign",
      "description": "New checkout flow",
      "start_at": 1751328000,
      "end_at": 1759190400,
      "is_archived": false,
      "coordinator": { "id": "3d5a685b-30d3-4c4e-9a71-6b6e3f7d8a11", "name": "Jane Doe", "email": "jane.doe@example.com" },
      "phases": [
        { "id": "8e8b0a7e-3b6d-4a6e-9f1e-2a8f9d4c5b21", "project_id": "0d69e436-03ae-4a80-aa82-8a2f1187689b", "name": "Default", "description": "", "finance_status": "", "approval_status": "approved", "is_default": true }
      ],
      "status": "On Hold",
      "health": "Amber",
      "health_description": "Waiting on payment provider",
      "status_history": [
        {
          "changed_at": 1757331600,
          "changed_by": { "id": "3d5a685b-30d3-4c4e-9a71-6b6e3f7d8a11", "name": "Jane Doe", "email": "jane.doe@example.com" },
          "application": "flow-ui",
          "changes": {
            "health": { "from": "Green", "to": "Amber" },
            "health_description": { "from": "Kick-off done", "to": "Waiting on payment provider" }
          }
        },
        {
          "changed_at": 1757245200,
          "changed_by": { "id": "3d5a685b-30d3-4c4e-9a71-6b6e3f7d8a11", "name": "Jane Doe", "email": "jane.doe@example.com" },
          "application": "flow-ui",
          "changes": {
            "status": { "from": "In Progress", "to": "On Hold" }
          }
        },
        {
          "changed_at": 1756640400,
          "changed_by": { "id": "3d5a685b-30d3-4c4e-9a71-6b6e3f7d8a11", "name": "Jane Doe", "email": "jane.doe@example.com" },
          "application": "flow-ui",
          "changes": {
            "status": { "from": null, "to": "In Progress" },
            "health": { "from": null, "to": "Green" },
            "health_description": { "from": null, "to": "Kick-off done" }
          }
        }
      ]
    }
  ]
}