> ## Documentation Index
> Fetch the complete documentation index at: https://docs.track3d.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Progress API Setup Guide

> Sign in, upload and retrieve progress records, and read external assets and asset categories using the Track3D Progress API.

The Track3D Progress API lets you retrieve and upload progress, sign users in, and read external assets and asset categories used in your projects.

<Note>
  Base URL: `https://progress-api.dev.track3d.ai` · Version: `v1`
</Note>

## Authentication

Include your API key on every request, with one exception.

```text theme={null}
x-api-key: YOUR_API_KEY
```

<Note>
  `/v1/users/signin` does not require the API key. Every other endpoint does.
</Note>

## Errors

| Status | Meaning |
| - | - |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 500 | Internal Server Error |

**Error shape (example)**

```json theme={null}
{
  "status": false,
  "message": "Error details"
}
```

***

## Sign in

```http theme={null}
POST /v1/users/signin
```

**Request body**

```json theme={null}
{
  "email": "user@example.com",
  "password": "••••••••"
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://progress-api.dev.track3d.ai/v1/users/signin" \
    -H "Content-Type: application/json" \
    -d '{"email":"user@example.com","password":"your_password"}'
  ```
</CodeGroup>

**Response — `201`**

```json theme={null}
{
  "success": true,
  "result": {
    "_id": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "contact": { "code": "string", "number": 0 },
    "dob": "string",
    "verified": true,
    "createdAt": "string",
    "updatedAt": "string",
    "__v": 0,
    "avatar": "string",
    "isSupportUser": true,
    "unReadNotifications": ["string"],
    "status": "string",
    "loginType": "string",
    "resetPasswordTimestamps": ["string"],
    "verificationTimestamps": ["string"],
    "userPreference": "string",
    "fullName": "string",
    "age": 0,
    "canResendVerification": true,
    "canResetPassword": true,
    "provider": "string",
    "token": "string",
    "refreshToken": "string"
  }
}
```

<Accordion title="Error response">
  ```json theme={null}
  { "status": false, "message": "Invalid credentials" }
  ```
</Accordion>

***

## Upload progress

```http theme={null}
POST /progress
```

**Request body**

```json theme={null}
{
  "projectId": "12345",
  "date": "2025-04-30",
  "status": "In Progress",
  "details": "Work started on the foundation."
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://progress-api.dev.track3d.ai/progress" \
    -H "x-api-key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "projectId":"12345",
      "date":"2025-04-30",
      "status":"In Progress",
      "details":"Work started on the foundation."
    }'
  ```
</CodeGroup>

**Response — `201`**

```json theme={null}
{
  "id": "progress1",
  "projectId": "12345",
  "date": "2025-04-30",
  "status": "In Progress",
  "details": "Work started on the foundation."
}
```

***

## Get progress (list)

```http theme={null}
GET /progress
```

**Query parameters**

| Name | Type | Required | Description |
| - | - | - | - |
| `projectId` | string | Yes | Project ID |
| `date` | string (date) | No | Filter by date `YYYY-MM-DD` |

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://progress-api.dev.track3d.ai/progress" \
    -H "x-api-key: $API_KEY" \
    --data-urlencode "projectId=12345" \
    --data-urlencode "date=2025-04-30"
  ```
</CodeGroup>

**Response — `200`**

```json theme={null}
[
  {
    "id": "progress1",
    "projectId": "12345",
    "date": "2025-04-30",
    "status": "Completed",
    "details": "Progress details here."
  }
]
```

***

## Get progress by ID

```http theme={null}
GET /progress/{id}
```

**Path parameters**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Progress entry ID |

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://progress-api.dev.track3d.ai/progress/progress1" \
    -H "x-api-key: $API_KEY"
  ```
</CodeGroup>

**Response — `200`**

```json theme={null}
{
  "id": "progress1",
  "projectId": "12345",
  "date": "2025-04-30",
  "status": "Completed",
  "details": "Foundation work completed."
}
```

***

## Get external asset categories (by project)

```http theme={null}
GET /api/external-asset-categories
```

**Query parameters**

| Name | Type | Required | Description |
| - | - | - | - |
| `project` | string | Yes | Project ID |

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://progress-api.dev.track3d.ai/api/external-asset-categories" \
    -H "x-api-key: $API_KEY" \
    --data-urlencode "project=pid"
  ```
</CodeGroup>

**Response — `200`**

```json theme={null}
{
  "success": true,
  "result": [
    {
      "status": "string",
      "drawing": "string",
      "_id": "string",
      "name": "string",
      "project": "string",
      "stages": [
        {
          "_id": "string",
          "name": "string",
          "sequence": 0,
          "color": "string",
          "uom": "string",
          "measurement": "string",
          "metrics": { "structureId": 0 },
          "predecessors": [0]
        }
      ],
      "description": "string",
      "createdAt": "2025-08-25T14:53:56.052Z",
      "updatedAt": "2025-08-25T14:53:56.052Z",
      "height": 0,
      "uom": "string",
      "id": "string"
    }
  ]
}
```

***

## Get external assets (by structure + category)

```http theme={null}
GET /api/external-assets
```

**Query parameters**

| Name | Type | Required | Description |
| - | - | - | - |
| `structure` | string | Yes | Structure ID |
| `category` | string | Yes | Category name or ID |

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://progress-api.dev.track3d.ai/api/external-assets" \
    -H "x-api-key: $API_KEY" \
    --data-urlencode "structure=sid123" \
    --data-urlencode "category=cat_name"
  ```
</CodeGroup>

**Response — `200`**

```json theme={null}
{
  "success": true,
  "result": [
    {
      "_id": "UJPeP7rjrmfK4sASkmYVVA",
      "category": "J0MqOKvgZqDBA5gQ6yaYhw",
      "shape": "Polyline",
      "points": [
        { "x": 518867.7664488507, "y": 3707128.323726985 }
      ],
      "properties": { "snapshotDate": "2000-01-01T00:00:00.000Z" },
      "snapshot": "1999-12-31T00:00:00.000Z",
      "doNotTrack": false,
      "stages": [
        { "_id": "XTU9LaDkj1_oiugf4y4Hkg", "percentage": 100, "date": "2024-06-24T00:00:00.000Z" }
      ]
    }
  ]
}
```

***

## Data models

<AccordionGroup>
  <Accordion title="Progress">
    ```json theme={null}
    {
      "id": "progress1",
      "projectId": "12345",
      "date": "2025-04-30",
      "status": "Completed",
      "details": "Progress details here."
    }
    ```

    | Field | Type | Notes |
    | - | - | - |
    | `id` | string | Generated ID |
    | `projectId` | string | Project identifier |
    | `date` | string (`YYYY-MM-DD`) | Progress date |
    | `status` | string | e.g. `In Progress`, `Completed` |
    | `details` | string | Free-form notes |
  </Accordion>

  <Accordion title="ExternalAsset">
    ```json theme={null}
    {
      "_id": "UJPeP7rjrmfK4sASkmYVVA",
      "category": "J0MqOKvgZqDBA5gQ6yaYhw",
      "shape": "Polyline",
      "points": [{ "x": 518867.7, "y": 3707128.32 }],
      "properties": { "snapshotDate": "2000-01-01T00:00:00.000Z" },
      "snapshot": "1999-12-31T00:00:00.000Z",
      "doNotTrack": false,
      "stages": [{ "_id": "XTU9LaD...", "percentage": 100, "date": "2024-06-24T00:00:00.000Z" }]
    }
    ```
  </Accordion>

  <Accordion title="ExternalAssetCategory">
    ```json theme={null}
    {
      "_id": "string",
      "name": "string",
      "project": "string",
      "stages": [
        { "_id": "string", "name": "string", "sequence": 0, "color": "string",
          "uom": "string", "measurement": "string", "metrics": { "structureId": 0 },
          "predecessors": [0] }
      ],
      "description": "string",
      "createdAt": "2025-08-25T14:53:56.052Z",
      "updatedAt": "2025-08-25T14:53:56.052Z",
      "height": 0,
      "uom": "string",
      "id": "string",
      "status": "string",
      "drawing": "string"
    }
    ```
  </Accordion>

  <Accordion title="SignIn (request / response)">
    **Request**

    ```json theme={null}
    { "email": "user@example.com", "password": "••••••••" }
    ```

    **Response (success)**

    ```json theme={null}
    {
      "success": true,
      "result": {
        "_id": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "contact": { "code": "string", "number": 0 },
        "dob": "string",
        "verified": true,
        "createdAt": "string",
        "updatedAt": "string",
        "__v": 0,
        "avatar": "string",
        "isSupportUser": true,
        "unReadNotifications": ["string"],
        "status": "string",
        "loginType": "string",
        "resetPasswordTimestamps": ["string"],
        "verificationTimestamps": ["string"],
        "userPreference": "string",
        "fullName": "string",
        "age": 0,
        "canResendVerification": true,
        "canResetPassword": true,
        "provider": "string",
        "token": "string",
        "refreshToken": "string"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Conventions

* Dates in progress lists use `YYYY-MM-DD`.
* Timestamps in assets/categories are ISO date-time strings.
* Only `/v1/users/signin` is unauthenticated. Every other endpoint requires `x-api-key`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.