> ## 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.

# Data API (DAAS) Introduction

> Programmatic, read-only access to your environment's project, benchmarking, reporting and community data

## What is the Data API?

The N3 Data API (Data-as-a-Service) gives your organisation programmatic, **read-only** access to the data held in your N3 environment — projects, risk assessments, development appraisals, benchmark snapshots, report metadata and anonymised community analytics. It is designed for integrations such as data warehouses, BI dashboards, portfolio reporting tools and scheduled exports.

Every request is scoped to a single N3 environment. The environment is determined entirely by your API key — it is never passed in the URL — so a key can only ever see the data belonging to the environment it was issued for.

<Note>
  The Data API is served from a dedicated service, separate from the main N3
  platform API. All endpoints are `GET` requests in the current version.
</Note>

## Base URL

```text theme={null}
https://data.n-3.co.uk
```

Your N3 contact or environment administrator will confirm the base URL for your deployment when your key is issued. All endpoint paths in this guide are relative to the base URL.

## Authentication

Authenticate every request with a **Data API key** in the `x-api-key` header. Data keys always start with the prefix `n3_data_`.

```bash theme={null}
curl "https://data.n-3.co.uk/data/projects" \
  -H "x-api-key: n3_data_xxxxxxxxxxxxxxxxxxxxxxxx"
```

### Obtaining a key

Data API keys are issued by the N3 team. Ask your N3 contact for a key for your environment. The full key is shown **once** at creation — store it securely (for example in a secrets manager). If a key is lost it cannot be recovered; revoke it and create a new one.

Keys can be deactivated, reactivated or permanently revoked by your environment administrator at any time.

<Warning>
  Only Data API keys (`n3_data_` prefix) work on `/data/*` endpoints. Platform
  keys, system keys and user session tokens are rejected. Likewise, a Data API
  key cannot be used against the main platform API.
</Warning>

## Scopes

Each key carries a set of scopes controlling which endpoint groups it may call:

| Scope             | Grants access to                            |
| ----------------- | ------------------------------------------- |
| `data:projects`   | `/data/projects` and its sub-resources      |
| `data:benchmarks` | `/data/benchmarks`                          |
| `data:reports`    | `/data/reports`                             |
| `data:community`  | `/data/community/*` (anonymised aggregates) |

New keys are granted `data:projects`, `data:benchmarks` and `data:reports` by default. The `data:community` scope must be granted explicitly.

Calling an endpoint without the required scope returns **403 Forbidden**:

```json theme={null}
{
  "message": "This API key does not have the required scope(s): data:community",
  "error": "Forbidden",
  "statusCode": 403
}
```

`GET /data/quota` requires no scope — any valid Data API key can check its own status. You can see the scopes granted to your key in the `scopes` field of the [quota response](/api-reference/data-api/rate-limits#checking-your-status-get-dataquota).

## Response conventions

* All responses are JSON.
* Identifiers (`id`, `project_id`, `environment_id`, …) are serialised as **strings**.
* Timestamps are ISO 8601 (UTC).
* Nullable fields are returned as `null`, never omitted.
* Monetary values are numbers in the environment's working currency (GBP unless configured otherwise).

## Error handling

| Status                  | Meaning                                                                                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`      | Missing, malformed, unknown, deactivated, revoked or expired key — or a non-Data key                                                                                        |
| `403 Forbidden`         | Valid key, but it lacks a required scope                                                                                                                                    |
| `404 Not Found`         | The resource does not exist **in your environment**. Resources belonging to other environments also return 404 — never 403 — so existence is not leaked across environments |
| `429 Too Many Requests` | Rate limit or quota exceeded — see [Rate limits & quotas](/api-reference/data-api/rate-limits)                                                                              |

## Next steps

<CardGroup cols={2}>
  <Card title="Endpoint catalogue" icon="list" href="/api-reference/data-api/endpoints">
    All endpoints with request parameters and response shapes
  </Card>

  <Card title="Rate limits & quotas" icon="gauge-high" href="/api-reference/data-api/rate-limits">
    Response headers, 429 handling and retry guidance
  </Card>

  <Card title="Worked examples" icon="terminal" href="/api-reference/data-api/examples">
    Copy-paste curl examples for common calls
  </Card>
</CardGroup>