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

# Endpoint Catalogue

> All Data API endpoints with parameters and response shapes

All endpoints are `GET`, require the `x-api-key` header, and return data scoped to your key's environment. Paths are relative to the base URL.

## Summary

| Endpoint                                  | Scope             | Returns                                                   |
| ----------------------------------------- | ----------------- | --------------------------------------------------------- |
| `GET /data/quota`                         | any               | Quota/throttle status for your key (never consumes quota) |
| `GET /data/projects`                      | `data:projects`   | Paginated project summaries                               |
| `GET /data/projects/:id`                  | `data:projects`   | Single project detail                                     |
| `GET /data/projects/:id/risk-assessments` | `data:projects`   | Initial risk assessments for a project                    |
| `GET /data/projects/:id/appraisals`       | `data:projects`   | Development appraisal lines for a project                 |
| `GET /data/benchmarks`                    | `data:benchmarks` | Paginated benchmark snapshots                             |
| `GET /data/reports`                       | `data:reports`    | Paginated report metadata                                 |
| `GET /data/reports/:id`                   | `data:reports`    | Report detail with risk statuses                          |
| `GET /data/community/analytics`           | `data:community`  | Anonymised community analytics (aggregates only)          |
| `GET /data/community/benchmarks`          | `data:community`  | Anonymised community benchmark aggregates                 |

`GET /data/quota` is documented on the [Rate limits & quotas](/api-reference/data-api/rate-limits) page.

## Pagination

List endpoints accept the standard pagination query parameters:

| Parameter | Type    | Default | Notes                                                                           |
| --------- | ------- | ------- | ------------------------------------------------------------------------------- |
| `limit`   | integer | `50`    | Maximum items per page. Capped at **200** — larger values are rejected with 400 |
| `offset`  | integer | `0`     | Number of items to skip                                                         |

Paginated responses wrap the items with a `pagination` object:

```json theme={null}
{
  "items": [],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 173
  }
}
```

`total` is the total number of matching items across all pages — keep requesting with an increasing `offset` until `offset + items.length >= total`.

## Projects

### `GET /data/projects`

Lists the environment's projects, newest first.

**Query parameters**: `limit`, `offset`, and optional `status` — one of `PENDING`, `IN_PROGRESS`, `DEFECTS_CORRECTION`, `COMPLETED`, `PRE_CONTRACT`, `NOT_YET_SECURED`.

**Response** — `items` is an array of project summaries:

```json theme={null}
{
  "items": [
    {
      "id": "1042",
      "name": "Riverside Quarter Phase 2",
      "project_reference": "RQ-2024-002",
      "client_reference": "CL-8891",
      "status": "IN_PROGRESS",
      "address": "12 Wharf Road, Manchester",
      "postcode": "M1 7ED",
      "latitude": 53.4794,
      "longitude": -2.2453,
      "site_area": 5200,
      "total_gifa": 14800,
      "total_cost": 32500000,
      "total_budget": 31000000,
      "gross_development_value": 48500000,
      "contract_form": "JCT Design and Build 2016",
      "contract_start_date": "2025-03-01T00:00:00.000Z",
      "contract_completion_date": "2027-06-30T00:00:00.000Z",
      "estimated_completion_date": "2027-08-15T00:00:00.000Z",
      "risk_score": 62.5,
      "number_of_units": 96,
      "archived": false,
      "last_modified_date": "2026-07-01T09:14:33.000Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 173 }
}
```

All fields other than `id`, `name`, `project_reference` and `archived` are nullable.

### `GET /data/projects/:id`

Returns a single project. Responds **404** if the project does not exist in your environment.

**Response** — all project summary fields above, plus:

```json theme={null}
{
  "description": "Mixed-use residential development…",
  "site_description": "Brownfield site adjacent to…",
  "proposed_procurement_structure": "Two-stage design and build",
  "funder_client": "Northbank Capital",
  "total_net_internal_area": 11200,
  "loan_facility_budget": 24000000,
  "loan_facility_out_turn": 24600000,
  "confidence_level": 3,
  "site_max_floors_above_ground": 12,
  "site_max_floors_below_ground": 1,
  "design_phase_weeks": 26,
  "liability_period": 12,
  "rule_off_date_for_valuations": "2026-06-25T00:00:00.000Z"
}
```

All additional detail fields are nullable.

### `GET /data/projects/:id/risk-assessments`

Returns the project's initial risk assessments (assessment sets with their risk items), newest first. Responds **404** if the project is not in your environment.

**Response** — an array (not paginated):

```json theme={null}
[
  {
    "id": "311",
    "created_date": "2026-05-14T10:22:01.000Z",
    "current_status": "Reviewed",
    "assessments": [
      {
        "id": "2051",
        "category": "Procurement",
        "value": "Two-stage tender agreed",
        "score": "3"
      }
    ]
  }
]
```

`current_status`, `value` and `score` are nullable.

### `GET /data/projects/:id/appraisals`

Returns the project's development appraisal lines in display order. Responds **404** if the project is not in your environment.

**Response** — an array (not paginated):

```json theme={null}
[
  {
    "id": "8802",
    "label": "Construction cost",
    "budget": 21500000,
    "out_turn": 22100000,
    "facility": 20000000,
    "created_date": "2025-02-11T16:40:12.000Z",
    "last_modified_date": "2026-06-30T08:05:44.000Z"
  }
]
```

`budget`, `out_turn`, `facility` and `last_modified_date` are nullable.

## Benchmarks

### `GET /data/benchmarks`

Lists the environment's benchmark snapshots.

**Query parameters**: `limit`, `offset`, and optional `projectId` to filter to a single project (which must be in your environment).

**Response**:

```json theme={null}
{
  "items": [
    {
      "id": "455",
      "project_id": "1042",
      "created_date": "2026-04-02T12:00:00.000Z",
      "type": "STANDARD",
      "bcis": 2870,
      "model_value": 2915,
      "model_value_lower": 2650,
      "model_value_upper": 3180,
      "source_health": 0.82,
      "community_value": 2890
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 12 }
}
```

`type` is `STANDARD` or `COMPOSITE`. All value fields (`bcis`, `model_value`, `model_value_lower`, `model_value_upper`, `source_health`, `community_value`) are nullable.

## Reports

### `GET /data/reports`

Lists the environment's report metadata.

**Query parameters**: `limit`, `offset`.

**Response**:

```json theme={null}
{
  "items": [
    {
      "id": "922",
      "type": "INTERIM",
      "period": "MONTHLY",
      "month": 6,
      "year": 2026,
      "edition": 14,
      "created_date": "2026-06-28T14:31:09.000Z",
      "last_modified_date": "2026-07-01T10:02:55.000Z",
      "project": {
        "id": "1042",
        "name": "Riverside Quarter Phase 2",
        "project_reference": "RQ-2024-002"
      }
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 58 }
}
```

### `GET /data/reports/:id`

Returns report detail. Responds **404** if the report is not in your environment.

**Response** — all report metadata fields above, plus `risk_statuses`:

```json theme={null}
{
  "risk_statuses": [
    {
      "id": "5120",
      "category": "Programme",
      "description": "Two-week slippage on frame package",
      "legend": "Amber",
      "legend_colour": "#F59E0B",
      "month": 6,
      "year": 2026
    }
  ]
}
```

`description`, `legend` and `legend_colour` are nullable.

## Community

Community endpoints require the explicitly-granted `data:community` scope. Responses are **always anonymised aggregates** — no raw community project rows are ever returned, and grouped buckets below the k-anonymity floor (`min_group_size`) are omitted entirely.

### `GET /data/community/analytics`

Anonymised analytics for the communities your environment belongs to.

**Response**:

```json theme={null}
{
  "min_group_size": 5,
  "total_community_projects": 418,
  "avg_cost_per_m2": 2740,
  "avg_total_cost": 28400000,
  "communities": [
    { "community_id": "7", "name": "UK Residential", "project_count": 302 }
  ],
  "by_building_function": [
    {
      "option_id": "14",
      "label": "Residential — apartments",
      "project_count": 121,
      "avg_cost_per_m2": 2810,
      "avg_total_cost": 31200000
    }
  ],
  "by_building_process": [
    {
      "option_id": "3",
      "label": "New build",
      "project_count": 264,
      "avg_cost_per_m2": 2695,
      "avg_total_cost": 27100000
    }
  ]
}
```

### `GET /data/community/benchmarks`

Anonymised community benchmark aggregates by building function.

**Response**:

```json theme={null}
{
  "min_group_size": 5,
  "omitted_buckets": 2,
  "by_building_function": [
    {
      "option_id": "14",
      "label": "Residential — apartments",
      "project_count": 121,
      "avg_cost_per_m2": 2810,
      "avg_total_cost": 31200000,
      "avg_footprint_cost": 2430,
      "avg_gifa": 12650,
      "median_cost_per_m2": 2770
    }
  ]
}
```

`omitted_buckets` is the number of buckets excluded because they fell below the k-anonymity floor. All averaged/median fields are nullable.