# BrickFlow API reference

Source: https://brickflow.ca/developers/api

> Every endpoint of the BrickFlow REST API that an API token can call, grouped by what it does, with its parameters, request fields and replies.

Developers

# BrickFlow API reference

299 endpoints your own systems and scripts can call, grouped by what they do.

## Before you start

Every request goes to `https://app.brickflow.site/api/v1` over HTTPS with your token in the `Authorization`header: `Authorization: Bearer YOUR_TOKEN`. Paths below start after `/api/v1`. [Create a token and read about errors](https://brickflow.ca/developers) on the developers page.

Each endpoint says which tokens can call it. **Any API token** means a token made with “Look at my data” or “Look at and change my data”. **Token that only reads** means “Look at my data” only. **Token that can change data** needs the “Look at and change my data” choice. A “Read reports only” token reaches only the endpoints marked **also Read reports only**.

A bill counts in the month its billing period starts. It is never split across months, so a bill that runs from 20 January to 19 February is a January bill.

Daily call limits: every organization may make a number of API and MCP calls a day, counted per UTC day across all its tokens: Free 200 (MCP only; the REST API is not included, so a call with a token or key answers 403 with a sentence saying so and that choosing Upgrade on the Subscription page adds API calls; waiting does not help, so there is no `Retry-After`), Essentials 1,000, Professional 10,000, Enterprise as its contract says. MCP calls count toward the same allowance on paid plans. Past the limit a call answers 429 with a `Retry-After` header (seconds until midnight UTC) and a sentence naming the plan and the way to raise the limit. Personal access tokens expire within one year: a token made without an expiry gets one a year out, and no token can be made for longer.

## Sections

-   [Portfolio and organization](#portfolio-and-organization) (46)
-   [Buildings](#buildings) (25)
-   [Spaces and equipment](#spaces-and-equipment) (17)
-   [Meters and readings](#meters-and-readings) (31)
-   [Bills](#bills) (27)
-   [Emissions and reports](#emissions-and-reports) (24)
-   [Alerts](#alerts) (21)
-   [Targets](#targets) (26)
-   [ENERGY STAR Portfolio Manager](#energy-star-portfolio-manager) (6)
-   [Green Button](#green-button) (6)
-   [Connected sources](#connected-sources) (26)
-   [Documents](#documents) (10)
-   [Leases](#leases) (4)
-   [Surveys and custom records](#surveys-and-custom-records) (16)
-   [Reference data](#reference-data) (4)
-   [Config](#config) (1)
-   [Legal policies](#legal-policies) (1)
-   [Pilot invite](#pilot-invite) (1)
-   [Staff](#staff) (7)

## Portfolio and organization (46)

GET `/entities/provenance`Who minted this record, what the edit dialogs call on open to warn before someone edits a field a later sync may re-assert (the edit is still allowed; only DELETE of a provider-synced record is refused, at the delete endpoints themselves).

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Whether a connector minted this record, and which |
| 400 | iri outside this org |
| 401 | Not authenticated |
| 403 | User not registered |

GET `/graph/export`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `format` | query | No | string.
`"turtle"` (default) or `"rdfxml"`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The caller's org graph, serialized as Turtle (default) or RDF/XML. |
| 400 | format= value |
| 401 | Not authenticated |
| 403 | Not an owner or admin of the active organization |

GET `/graph/first-seen`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | For each equipment, meter and space in the caller's org graph: when it first appeared and which connectors minted it |
| 401 | Not authenticated |
| 500 | The graph could not be read |

GET `/graph/schema`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Caller's org graph shape (classes/edges/attributes) plus the shared gk: reference-data instance layer; counts are null for a person limited to some buildings |
| 401 | Not authenticated |

GET `/graph/stats`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Quad counts for the caller's org graph and the shared vocabulary graph; a graph with no quads has no row |
| 401 | Not authenticated |
| 403 | This is outside the buildings shared with you. Ask the person who invited you for access. |
| 500 | A graph's size could not be read |

GET `/me/getting-started`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The Getting started steps the caller finished |
| 401 | Not authenticated |
| 500 | The steps could not be read |

PUT `/me/getting-started/{step}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `step` | path | Yes | string.
The step name: lowercase letters, digits and dashes

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The step is marked finished for the caller |
| 400 | The step name is not valid |
| 401 | Not authenticated |
| 500 | Not saved |

GET `/me/later-questions`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The questions the caller answered or put away in this organization |
| 401 | Not authenticated |
| 500 | Not read |

PUT `/me/later-questions/{key}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `key` | path | Yes | string.
The question's id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `answer` | string | No | 
The picked choice's id, or null for Not now.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 204 | Saved; a question already answered keeps its first answer |
| 400 | The question or choice id is not a short lowercase slug |
| 401 | Not authenticated |
| 500 | Not saved |

GET `/me/notification-pref`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The caller's own notification preference |
| 401 | Not authenticated |
| 403 | User not registered |

PUT `/me/notification-pref`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | string | Yes | 
`"off"` | `"daily"` | `"immediate"`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Preference saved |
| 400 | Unknown mode |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/me/pilot-invite/claim`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `token` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Answers attached to the caller's own new organization, or claimed false when the link is not live or the caller is not the owner or admin of an organization they created |
| 401 | Not authenticated |

GET `/me/setup-emails`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Whether the setup emails concern the caller, and their choice |
| 401 | Not authenticated |
| 403 | User not registered |

PUT `/me/setup-emails`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `subscribed` | boolean | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Choice saved |
| 401 | Not authenticated |
| 403 | User not registered |

GET `/me/tour-progress`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Where the caller left the welcome tour; progress is null when never started |
| 401 | Not authenticated |
| 500 | The progress could not be read |

PUT `/me/tour-progress`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `finished` | boolean | No |  |
| `step` | integer | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Saved for the caller |
| 400 | The step is not a number from 0 to 99 |
| 401 | Not authenticated |
| 500 | Not saved |

GET `/modules`

Any API token, also Read reports only

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Registered calculation modules |
| 401 | Not authenticated |
| 403 | User not registered |

GET `/modules/{id}/meter-control`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | string.
g. ghg-scope12)

 |
| `building` | query | Yes | string.

Full building IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | This building's carrier-classified meters with the operational-control label a person gave each, and the organization's reporting perspective |
| 400 | `building` is not a valid IRI |
| 401 | Not authenticated |
| 403 | A scoped member with no grant in this report's domain |
| 404 | Unknown module id |
| 500 | Error listing the building's meters or reading the stored labels |

PATCH `/modules/{id}/meter-control`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | string.
Module id

 |
| `building` | query | Yes | string.

Full building IRI, URL-encoded.

 |

#### Request body

application/json, required.

The PATCH body: an object with a `changes` list.

/meter-inclusion `takes, so that neither endpoint's body can be posted to the other by accident.`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `changes` | list of object | Yes |  |
| `changes[].control` | string | No | One of: landlord, tenant.
Who operates one meter, on the wire.

Its own type rather than \[`gk_core::store::MeterControl`\] with serde bolted on: the spelling a client sends is this endpoint's published contract, where the calculation enum must stay free to grow a variant without that being an API change. The two convert explicitly, below.

 |
| `changes[].meter_iri` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Labels applied; the refreshed control state for this building/module |
| 400 | Invalid building IRI, or a meter\_iri that is not one of this building's carrier-classified meters for this module |
| 401 | Not authenticated |
| 403 | Only owners and admins can change meter control |
| 404 | Unknown module id |
| 500 | Error writing a label, or reading the refreshed state back |

GET `/modules/{id}/meter-inclusion`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | string.
g. eui-site, ghg-scope12)

 |
| `building` | query | No | string.

Full building IRI, URL-encoded. Omitted: the org-wide response.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | building omitted: every building with at least one carrier-classified meter for this module (for a scoped member, at least one they can see), each grouped the same way |
| 400 | `building` is present but not a valid IRI |
| 401 | Not authenticated |
| 403 | A scoped member with no grant in this report's domain |
| 404 | Unknown module id |

PATCH `/modules/{id}/meter-inclusion`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | string.
Module id

 |
| `building` | query | Yes | string.

Full building IRI, URL-encoded.

 |

#### Request body

application/json, required. list of object

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Overrides applied; the refreshed inclusion state for this building/module. An org-wide owner, admin or editor changes the organization's set; a scoped member changes only their OWN set, which applies to their own reports and never to anyone else's |
| 400 | Invalid building IRI, unknown module id, or a meter\_iri not among this building's carrier-classified meters for this module |
| 401 | Not authenticated |
| 403 | An org-wide viewer, or a scoped member naming a meter they cannot see or do not control |

GET `/modules/{id}/results`

Any API token, also Read reports only

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | string.
g. ghg-scope12)

 |
| `from` | query | Yes | string.

g. `2024-01-01T00:00:00Z`).

 |
| `to` | query | Yes | string.

Exclusive period end, RFC 3339.

 |
| `compare_from` | query | No | string.

Optional compare-period start (RFC 3339); requires `compare_to`.

 |
| `compare_to` | query | No | string.

Optional compare-period end (RFC 3339); requires `compare_from`.

 |
| `unit` | query | No | string.

ts`'s display-unit menus.`

 |
| `area_unit` | query | No | string.

Optional caller-selected output area-unit override (`ft2`/`m2`), `eui-site`'s intensity denominator only; ignored by other modules.

 |
| `factors_as_of` | query | No | string.

1-002), so a report made before a value was changed can be reproduced. Absent, the values in force now.

 |
| `by_carrier` | query | No | boolean.

`ghg-scope12` only (OUT-14, the portfolio dashboard): also return one `EmissionsFrom<Carrier>` row per fuel beside each building's Scope 1 and 2 total. Off unless `true`.

 |
| `months` | query | No | boolean.

`true`: also return `monthly`, the per-fuel rows of each calendar month of the primary period (at most 60), computed in the same pass. Implies `by_carrier`.

 |
| `by_scope` | query | No | boolean.

`ghg-scope12` only (the portfolio dashboard, emissions by scope): also return, for each fuel, its part of the building's Scope 1 or Scope 2 row (`Scope1EmissionsFrom<Carrier>`, `Scope2LocationBasedEmissionsFrom<Carrier>`). Off unless `true`.

 |
| `building` | query | No | string.

Full building IRI: keep only that building's rows (the dashboard's building filter).

 |
| `fuel` | query | No | string.

): keep only that fuel's per-fuel rows (the dashboard's fuel filter).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Results and completeness gaps computed LIVE for the requested period(s), one entity walk serves both periods; nothing is stored. Empty results with gaps explain themselves; empty results with no gaps mean the org has no evaluable buildings. |
| 400 | Invalid from/to/compare\_from/compare\_to |
| 401 | Not authenticated |
| 403 | User not registered, or a scoped role with no Sustainability grant |
| 404 | Unknown module id |

GET `/org`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The active org, the caller's role, and (for org-wide roles) the member list |
| 401 | Not authenticated |
| 403 | User not registered |

PATCH `/org`Renames the active org.rs\`'s portfolio-root label), this is the only way to give that name a customer-chosen replacement.

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Organization renamed |
| 400 | Blank or over-length name |
| 401 | Not authenticated |
| 403 | User not registered, or lacks owner/admin role |
| 409 | Another organization is already named this (ignoring case and spacing) |

GET `/org/access-requests`

Token that only reads

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Pending access requests |
| 403 | Only owners and admins |

GET `/org/audit`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The newest 100 membership, permission and setting events, plus the newest 100 sign-ins, bill opens and exports, plus the newest 100 refused invitation links and access codes, plus the newest 100 requests made through Claude, newest first |
| 403 | Only owners and admins can read the audit log |

GET `/org/audit-log`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `person` | query | No | string.
A person's name, as the list shows it.

 |
| `record_type` | query | No | string.

A record type's name, as the list shows it ("Bill").

 |
| `from` | query | No | string.

First day, `YYYY-MM-DD`, inclusive.

 |
| `to` | query | No | string.

Last day, `YYYY-MM-DD`, inclusive.

 |
| `limit` | query | No | integer (int64). |
| `offset` | query | No | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Data changes newest first, with the counts and filter choices the screen shows |
| 400 | A date is not year-month-day |
| 403 | Only owners, admins and editors can read the audit log |

GET `/org/audit-log/corrections/{batch_id}`The changed values behind one Audit log row.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `batch_id` | path | Yes | integer (int64).
The `corrections_ref` of an Audit log row

 |
| `from` | query | No | string (date-time).

Only readings whose period starts at or after this time (RFC 3339). Meters only.

 |
| `to` | query | No | string (date-time).

Only readings whose period starts at or before this time (RFC 3339). Meters only.

 |
| `limit` | query | No | integer (int64).

Corrections per page, 1 to 500; 100 when absent.

 |
| `offset` | query | No | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The values one correction summary row changed, in period order |
| 403 | Only owners, admins and editors can read the audit log |
| 404 | No such change in your organization |
| 500 | Reading the changes failed |

GET `/org/audit-log/export`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `person` | query | No | string.
A person's name, as the list shows it.

 |
| `record_type` | query | No | string.

A record type's name, as the list shows it ("Bill").

 |
| `from` | query | No | string.

First day, `YYYY-MM-DD`, inclusive.

 |
| `to` | query | No | string.

Last day, `YYYY-MM-DD`, inclusive.

 |
| `limit` | query | No | integer (int64). |
| `offset` | query | No | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | CSV of the changes under the filters: When (UTC), Who, Change, Record type, Record, BrickFlow ID, Field, Before, After |
| 400 | A date is not year-month-day |
| 403 | Only owners, admins and editors can read the audit log |

GET `/org/edit-access-requests`

Token that only reads

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Pending edit-access requests |
| 403 | Only owners and admins |

GET `/org/edit-access-requests/mine`

Token that only reads

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Whether the caller has a request waiting: {pending} |
| 401 | Sign in first |

GET `/org/entity-access-requests`

Token that only reads

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Pending entity-specific access requests |
| 403 | Only owners and admins |

GET `/org/grantable-owners`entity\_iri=…\`, the Grant-access affordance's data (plan §14).

Any API token

Plan §14 puts a "Grant access" action next to any owner the Building Explorer tags as a BrickFlow organization.

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `entity_iri` | query | Yes | string.
The entity whose recorded owners to resolve

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Recorded owners that are linked BrickFlow organizations |
| 400 | Missing entity\_iri, or one outside this organization |
| 401 | Not authenticated |
| 403 | Only owners and admins |

GET `/org/grantable-owners-org-wide`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Recorded owners, org-wide, that are linked BrickFlow organizations with no share issued yet |
| 401 | Not authenticated |
| 403 | Only owners and admins |

GET `/org/graph-entities`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every entity in this org's graph, flat, for the permissions builder's tree picker |
| 403 | Only owners and admins |

GET `/org/members/{membership_id}/grants`

Token that only reads

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `membership_id` | path | Yes | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The member's grant rows |
| 403 | Only owners and admins |
| 404 | No such member in this org |

GET `/org/my-grants`grants\` once, however many domains it covers, labelled via \[\`grant\_entity\_meta\`\], sorted by label then IRI. Reads nothing but the caller's own membership (what \`AuthCtx::resolve\` already loaded), so it is open to every role; an org-wide role has no grants and gets \`\[\]\` without a graph read. \`/auth/session\` stays light: only the welcome screen asks for this.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The places the caller was granted, one row per entity; empty for an org-wide role |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | The caller's organization could not be resolved |

POST `/org/onboarding`Self-reporting, not a permission change, any authenticated, registered member may mark their OWN membership onboarded, no role gate.g. a "skip" action that doesn't ask about persona) never erases an already-declared persona: the UPDATE COALESCEs onto the existing value. Unlike \`org\_renamed\` above, this is a personal preference, not an org-visible permission change, so it is not audited.

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `goals` | list of string | No | 
1). Absent keeps what is stored.

 |
| `join_path` | string | No | 

json). Absent keeps what is stored.

 |
| `persona` | string | No |  |
| `planned_sources` | list of string | No | 

The data sources the member plans to bring. Absent keeps what is stored.

 |
| `start_goal` | string | No | 

The goal marked "start here"; must be one of `goals`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Onboarding recorded for the caller's own membership |
| 400 | Persona over the stored column's length |
| 401 | Not authenticated |
| 403 | User not registered |

PUT `/org/onboarding/home-cards`1-030): Home's "Hide for now" on Get set up and the close on the Discover line, kept on the caller's OWN membership so the choice follows the person to any browser. Like the onboarding answers above it is a personal preference: any registered member, scoped roles included, may set it for themselves, it touches only their row in the active organization, and it is not audited.

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `discover_closed` | boolean | No | 
true closes the Discover line that follows a finished set-up; false opens it again. Absent keeps what is stored.

 |
| `setup_hidden` | boolean | No | 

true hides Home's "Get set up" card for this member in this organization; false shows it again. Absent keeps what is stored.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The caller's Home card choices in the active organization |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No membership in the active organization |

GET `/org/org-grants`The granting organization's outgoing shares, newest first.

Token that only reads

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every share this organization has issued, newest first |
| 401 | Not authenticated |
| 403 | Caller cannot manage sharing (Owner/Admin only) |

PUT `/org/reporting-perspective`Declares which side of a lease this organization reports from.

Token that can change data

Owner/admin only, through `authz`'s existing org-settings gate: an EDITOR who may correct a meter reading may not decide whose emissions that reading is. The gate's own refusal wording is returned unchanged (unlike `meter-control`'s, which needed its own), "change organization settings" already describes what a refused caller tried to do.

EVERY declaration is audited, including one that re-states what is already stored, deliberately unlike `org_update`'s `IS DISTINCT FROM` no-op above. A rename re-submitted by a page reload is noise; "somebody re-affirmed on this date which side of the lease we report from" is exactly the answer a customer asking why their Scope 2 moved is owed.

#### Request body

application/json, required.

Which side of a lease this organization reports from, on the wire.

Two bodies also mean neither can be posted to the other by accident, the same reasoning `modules_api::MeterControlPatchRequest` records one table over.

The field is a plain `String` parsed by \[`ReportingPerspective::from_stored`\], not a serde enum like `modules_api::MeterControlLabel`: the accepted spellings ARE the stored ones (migration 0089's CHECK), so there is nothing to translate between wire and storage, and refusing here rather than in the extractor is what lets the refusal name the two values a caller may send instead of serde's "unknown variant" wording.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reporting_perspective` | string | Yes | 
`"owner"` or `"occupier"`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The stored reporting perspective |
| 400 | A spelling outside `owner` / `occupier` |
| 401 | Not authenticated |
| 403 | User not registered, or lacks owner/admin role |
| 500 | Error saving the reporting perspective |

PUT `/org/tenant-area-visibility`Switches whether tenants and contractors with access to only part of a building also see the building's whole floor area.

Token that can change data

Owner/admin only, through the same org-settings gate as the reporting perspective: an editor who may correct a reading may not decide what a tenant is shown. EVERY write is audited, including one that re-states the stored value, so a customer asking when this was last confirmed has an answer. This endpoint only stores the choice; the reads of building areas apply it.

#### Request body

application/json, required.

Whether a tenant or contractor who can see only part of a building also sees the building's whole floor area, on the wire.

Its own endpoint, like the reporting perspective above and for the same reason: a rename corrects a label, this decides what other people are shown. The body names no organization; the caller's own is resolved from the session.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tenants_see_building_area` | boolean | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The stored value |
| 400 | The body is not `{"tenants_see_building_area": true|false}` |
| 401 | Not authenticated |
| 403 | User not registered, or lacks owner/admin role |
| 500 | Error saving the setting |

POST `/owners`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/owners`. Distinct from every other create body here: an owner is a party, not a place, so it takes no parent, no area, no jurisdiction and no address, a label, and optionally the BrickFlow organization this owner turns out to BE.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | string | Yes |  |
| `linked_org_id` | integer | No | 
id `this owner already is, when the owner is itself a BrickFlow organization. Omitted, the common case, the owner is a plain external label.`

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Owner created and its provenance-carrying ingest job committed |
| 400 | Empty/oversize label, or a linked\_org\_id that is not a positive 32-bit integer |
| 401 | Not authenticated |
| 403 | User not registered, or a building-scoped role (an owner attaches to no building, so it is outside every granted subtree) |
| 500 | Database or ingest error |

GET `/portfolio/building-locations`\`GET /api/v1/portfolio/building-locations\` -- the portfolio map's pin data.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every geocoded building (Google Maps lat/lng on file) the caller may see -- org-wide for org-wide roles, filtered to granted buildings for scoped roles |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the locations or the caller's visible buildings |

GET `/portfolio/duplicate-buildings`Report buildings that are probably the same one recorded twice.

Any API token

WHY THIS EXISTS AND WHAT IT IS NOT. Two sources describing one building mint two graph nodes -- ENERGY STAR Portfolio Manager keys on its own property id, manual entry on a user-supplied key -- and nothing resolves between them, so every portfolio-wide total counts that building twice. This endpoint does NOT fix that (see ledger finding LB-001: the real fix is an identity layer, and its central decision -- a reversible alias edge versus rewriting one node onto the other -- is not one to make in passing). It makes the problem VISIBLE, so a doubled total can say it might be overstated instead of presenting itself as correct.

SEPARATE ENDPOINT, NOT A FIELD ON `/portfolio/summary`, and the reason is measured: the query behind it costs ~300 ms over 100 buildings, while `/portfolio/summary` measures 157 ms in the perf ledger. Folding it in would roughly triple a watched endpoint and trip the ledger's own regression threshold (>=40 % and >=250 ms) on the next nightly. A diagnostic that makes the product slower for everyone who is not reading it is a bad trade.

Authorization reuses the space tree exactly as `building_areas_get` does, so a scoped role can never be shown a building the tree hides from it.

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | e. probably one physical building recorded twice. Empty means none detected, NOT that none exist |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The addresses or the stored decisions could not be read, never an empty list, which would mean 'no duplicates' |

GET `/portfolio/summary`

Any API token, also Read reports only

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Portfolio-wide KPI counts, org-wide for org-wide roles, summed over the caller's granted buildings for scoped roles. A granted building whose graph reads failed is named in `unreadable_buildings` and adds no space, equipment or area |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | The graph store did not answer a whole-organization count |

## Buildings (25)

GET `/building-links`The decisions this caller may see.

Any API token

SCOPED THROUGH THE TREE, AND BOTH SIDES OF IT. A row is listed only when BOTH of its buildings are Buildings in the caller's own space tree (`topology_api::visible_building_iris`, the same set `spaces_tree` and `/buildings/areas` prune to). Half a pair is not a pair: listing a row because the caller holds ONE of its buildings would hand them the IRI of the other, a building their grants deliberately hide, through the row itself. An org-wide role's tree is the whole org, so they see every decision.

status= `NARROWS, IT NEVER WIDENS: it is applied after the tree filter, so no status can reach a row the caller may not see. An unrecognised value is a 400 rather than "all", because a caller that asked for confirmations and was handed dismissals too would offer to unlink pairs that nothing is folding.`

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `status` | query | No | string.
`confirmed` or `dismissed`. OMITTED LISTS BOTH, which is what a caller showing the whole decision history wants; the card asks for one kind at a time because the two mean different things to it, a confirmation is the only row it can offer "Unlink" on.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every duplicate-building decision whose BOTH buildings are visible to the caller, narrowed to `status` when one is given |
| 400 | `status` is neither 'confirmed' nor 'dismissed' |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | The decisions or the caller's space tree could not be read |

POST `/building-links`Decide one candidate pair: confirm it (naming which record to keep) or dismiss it.

Token that can change data

Storing the decision is all this does, beyond settling the duplicate-meter proposals a confirmed pair made possible when it is dismissed (an open one is withdrawn, a confirmed one refuses the dismissal) and starting a duplicate-meter sweep when it changes which meters count together. Nothing in the graph moves.

#### Request body

application/json, required.

Body of `POST /api/v1/building-links`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `basis` | string | No | 
Why the pair was proposed: `address_exact` (the default) or `same_id`, a workbook building and an ENERGY STAR property with the same ID. Anything else is refused.

 |
| `building_a_iri` | string | Yes |  |
| `building_b_iri` | string | Yes |  |
| `decision` | string | Yes | 

`confirmed`, these two records are one building, or `dismissed`, they are two different buildings that happen to share an address.

 |
| `primary_iri` | string | No | 

The building the pair counts as. REQUIRED when `decision` is `confirmed`, and must be one of the two; ignored on a dismissal, which folds nothing and therefore has no primary.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The decision as stored; a second decision about the same pair replaces the first |
| 400 | Unknown decision or basis, the same building twice, or a confirmation whose primary\_iri is missing or is not one of the pair |
| 401 | Not authenticated |
| 403 | Only owners, admins and editors, org-wide |
| 404 | One of the IRIs is not a building in this organization |
| 409 | Confirming this pair would chain: one of the two already folds away, or is already what another pair folds into; or dismissing a confirmed pair while a duplicate meter confirmed across its two records still excludes one copy |
| 500 | The organization's buildings, its stored decisions or its duplicate-meter decisions could not be read |

DELETE `/building-links/{id}`Withdraw a decision.

Token that can change data

The row is DELETED, not marked: a decision that has been taken back should leave the pair exactly as it was before anyone touched it, and a tombstone would have to be excluded by every reader forever. The pair becomes a candidate again on the next read of `/api/v1/portfolio/duplicate-buildings`, but only if the two addresses still match, because that list is recomputed and never stored.

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The decision is withdrawn; if the two addresses still match, the pair is a candidate again on the next read |
| 401 | Not authenticated |
| 403 | Only owners, admins and editors, org-wide |
| 404 | No such decision in this organization |
| 409 | A duplicate meter confirmed across the pair's two records still excludes one copy; include it again on the meter inclusion panel first |
| 500 | The stored decisions or duplicate-meter decisions could not be read, or the row could not be deleted |

GET `/buildings/{id}/equipment`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Building database id

 |
| `iri` | query | No | string.

Full building IRI, URL-encoded, takes precedence over the path id.

 |
| `month` | query | No | string.

Reporting month (`YYYY-MM`), see \[`EquipmentInfo::status_as_of`\].

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Building's equipment, optionally with each item's status as of a reporting month |
| 400 | `iri` given but not a valid IRI, or `month` given but not a valid YYYY-MM |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the equipment listing, the caller's granted scope or the status history |

GET `/buildings/{id}/espm-target`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Building database id

 |
| `iri` | query | No | string.

Full building IRI, URL-encoded, takes precedence over the path id.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The building's PM-configured performance target, or null if none is set |
| 400 | `iri` given but not a valid IRI |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered, or scoped to a space rather than the whole building |
| 500 | The graph store did not answer the target read |

GET `/buildings/{id}/floors`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Building database id

 |
| `iri` | query | No | string.

Full building IRI, URL-encoded, takes precedence over the path id.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Building's floors, with room counts |
| 400 | `iri` given but not a valid IRI |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the floor listing or the caller's granted scope |

GET `/buildings/{id}/meters`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Building database id

 |
| `iri` | query | No | string.

Full building IRI, URL-encoded, takes precedence over the path id.

 |
| `extra_readings` | query | No | string.

`1` (or `true`, `yes`, `on`) lists each meter's extra readings (demand, energy sent to the grid). That costs one extra graph read, so it is off unless asked for; any other value, or none, leaves the readings out.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Building's meters, with series links where present, and their extra readings when `extra_readings` is asked for |
| 400 | `iri` given but not a valid IRI |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the meter listing or the caller's granted scope |

GET `/buildings/{id}/reported-metrics`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Building database id

 |
| `iri` | query | No | string.

Full building IRI, URL-encoded, takes precedence over the path id.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | ENERGY STAR Portfolio Manager-reported metrics for the building |
| 400 | `iri` given but not a valid IRI |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the reported-metrics read |

GET `/buildings/{id}/summary`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Building database id

 |
| `iri` | query | No | string.

Full building IRI, URL-encoded, takes precedence over the path id.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Floor/room/equipment/meter counts |
| 400 | `iri` given but not a valid IRI |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer a count or the owners read |

GET `/buildings/areas`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `include` | query | No | string.
Comma-separated, any of: `owners` adds each building's recorded ownership stakes, where the caller may see them; `control` adds `tenant_controlled` (see \[`BuildingAreaFacts::tenant_controlled`\]).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Area facts for every visible building. gross\_area is the building's own area; a scoped reader also gets granted\_area, their own share, and no gross\_area when the organization hides it (tenants\_see\_building\_area) |
| 400 | `include` given with a value other than `owners` or `control` |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The space tree, the buildings' area facts or (with `owners`) their ownership stakes could not be read from the graph store |

GET `/buildings/certifications`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The building's full IRI.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The building's certifications (an empty list when there are none) |
| 401 | Not authenticated (no session and no valid API token) |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or the building is outside a limited member's Sustainability access |
| 404 | The IRI is not in the caller's organization |
| 500 | Reading the certifications failed |

POST `/buildings/certifications`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The building's full IRI.

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `awarded_on` | string | No | 
"YYYY-MM-DD".

 |
| `certificate_ref` | string | No |  |
| `certifying_body` | string | No |  |
| `expires_on` | string | No | 

"YYYY-MM-DD", not before `awarded_on`.

 |
| `level` | string | No |  |
| `points` | number | No | 

99 (a Fitwel score, LEED points).

 |
| `rating_system` | string | No | 

The rating system or sub-type: BD+C, O+M. Free text; the form offers the usual ones.

 |
| `scheme` | string | Yes | 

`leed`, `boma_best`, `energy_star`, `well`, `fitwel`, `zero_carbon_building` or `other`.

 |
| `scheme_other` | string | No | 

Required (non-blank) when `scheme` is `other`, and refused for every other scheme.

 |
| `version` | string | No | 

1, v5. Free text; the form offers the usual ones.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 201 | Created |
| 400 | A field is not valid; the body names it |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify this organization's data, or the building is outside your Sustainability write access |
| 404 | The IRI is not a building of the caller's organization |
| 500 | Saving the certification failed |

PUT `/buildings/certifications/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The building's full IRI.

 |
| `id` | path | Yes | integer (int64).

building\_certification id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `awarded_on` | string | No | 
"YYYY-MM-DD".

 |
| `certificate_ref` | string | No |  |
| `certifying_body` | string | No |  |
| `expires_on` | string | No | 

"YYYY-MM-DD", not before `awarded_on`.

 |
| `level` | string | No |  |
| `points` | number | No | 

99 (a Fitwel score, LEED points).

 |
| `rating_system` | string | No | 

The rating system or sub-type: BD+C, O+M. Free text; the form offers the usual ones.

 |
| `scheme` | string | Yes | 

`leed`, `boma_best`, `energy_star`, `well`, `fitwel`, `zero_carbon_building` or `other`.

 |
| `scheme_other` | string | No | 

Required (non-blank) when `scheme` is `other`, and refused for every other scheme.

 |
| `version` | string | No | 

1, v5. Free text; the form offers the usual ones.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Updated; the building never changes |
| 400 | A field is not valid; the body names it |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify this organization's data, or the building is outside your Sustainability write access |
| 404 | No certification with this id on this building in your organization |
| 500 | Saving the certification failed |

DELETE `/buildings/certifications/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The building's full IRI.

 |
| `id` | path | Yes | integer (int64).

building\_certification id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify this organization's data, or the building is outside your Sustainability write access |
| 404 | No certification with this id on this building in your organization |
| 500 | Deleting the certification failed |

GET `/buildings/espm-facts`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | ENERGY STAR Portfolio Manager-reported metrics and PM target for every building that has either, across the visible portfolio |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the reported metrics or the PM targets |

GET `/buildings/explorer`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | No | string.
Full building IRI, URL-encoded.

 |
| `from` | query | No | string.

building= `answers it (RFC 3339).`

 |
| `to` | query | No | string.

Exclusive end of the intensity period, RFC 3339.

 |
| `per` | query | No | string.

`month`: the intensity period is one Specific month, per month.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | building= answers). Each part is {ok: what its own route answers} or {error: {status, message}}, and each keeps its own role check: a part the caller may not read is an error, never an empty list. The geocode part answers 403 to an API key, as its own route does. With from and to, an intensity part too: the building's Site EUI and Source EUI as GET /api/v1/energy/intensity answers it. |
| 400 | No building iri, or an invalid one |
| 401 | Not authenticated, or an invalid, revoked or expired API token |

GET `/buildings/fact-history`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The building's IRI.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every recorded row of the building's dated facts (occupancy, gross area, owners' stakes, ENERGY STAR score), cleared rows included with a null value, ordered by fact, then subject, then newest start date first. Each row says who recorded it, when, from which source and which graph job carried it; an owner's stake row carries the owner's current name beside its IRI |
| 400 | `iri` is not an IRI |
| 401 | Not authenticated |
| 403 | User not registered, or your access is limited to specific buildings and does not include this one |
| 404 | The building is not a building of the caller's organization |
| 500 | The history could not be read |

GET `/buildings/facts-as-of`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The building's IRI.

 |
| `at` | query | No | string (date).

The day to read the building on (`YYYY-MM-DD`), the whole day counting. Omitted means today.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | What BrickFlow recorded about the building on the day: occupancy, gross area, owners' stakes and ENERGY STAR score from the dated history (each says when it began, where it came from and who entered it; an owner's stake row carries the owner's current name beside its IRI), plus the leases in force, the certifications held and the latest property value on that day. A fact first recorded after the day has no value and says when it was first recorded. Nothing is read from before a fact's first recorded date |
| 400 | `iri` is not an IRI, or `at` is not a date |
| 401 | Not authenticated |
| 403 | User not registered, or your access is limited to specific buildings and does not include this one |
| 404 | The building is not a building of the caller's organization |
| 500 | The facts could not be read |

GET `/buildings/meter-counts`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Meter count of every building the caller's space tree shows, 0 when it has none, sorted by IRI |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the space tree or the meter count |

PATCH `/buildings/occupancy`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Request body

application/json, required. any

The body the handler reads: the edit plus the date it starts to hold.

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Occupancy set/cleared; a gk:ManualEntry job committed |
| 400 | Invalid iri, valid\_from after today, occupancy\_percentage not a multiple of 5 in \[0,100\], iri outside this org, iri not a building, or refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered, or outside their granted write scope |
| 404 | iri does not exist in this org's graph, or does not name a building |
| 500 | Database or ingest error |

GET `/certifications`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every certification of the buildings the caller may read: all of the organization's for an organization-wide role, only the granted buildings' for a member limited to specific buildings (Sustainability area) |
| 401 | Not authenticated (no session and no valid API token) |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 500 | Reading the certifications failed |

GET `/property-values`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `building` | query | No | string.
Only this building's records (full IRI, URL-encoded).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every property value the caller may read, optionally of one building, newest valuation first within a building. A contractor sees a value only when a Financial grant covers its building; a tenant sees none, and so does a token narrowed to buildings |
| 400 | building= is blank |
| 401 | Not authenticated (no session and no valid API token) |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | building= the answer is an empty list) |
| 500 | Error reading the values or the graph |

POST `/property-values`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/property-values` and `PUT /api/v1/property-values/{id}`: the whole record, every time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | Yes | 
01 once rounded to the cent, below 10000000000000.

 |
| `basis` | string | Yes | 

One of `appraisal`, `assessment`, `purchase_price`, `book_value`, `other`.

 |
| `building_iri` | string | Yes | 

A building of this organization (full IRI).

 |
| `currency` | string | No | 

Three letters, trimmed and upper-cased. Omit or `null`: a POST stores the organization's default currency (CAD when it has none) and a PUT keeps the stored one.

 |
| `note` | string | No | 

At most 1000 characters; blank is stored as `null`.

 |
| `valued_on` | string | Yes | 

`YYYY-MM-DD`, not after today. One value per building per date.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created |
| 400 | 01 or is 10000000000000 or more, a currency that is not three letters, an unknown basis, or a note over 1000 characters |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify property values, or the building is outside your granted Financial write scope |
| 409 | This building already has a value recorded on that date |
| 500 | Error reading the graph or writing the value |

PUT `/property-values/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
property value id

 |

#### Request body

application/json, required.

Body of `POST /api/v1/property-values` and `PUT /api/v1/property-values/{id}`: the whole record, every time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | Yes | 
01 once rounded to the cent, below 10000000000000.

 |
| `basis` | string | Yes | 

One of `appraisal`, `assessment`, `purchase_price`, `book_value`, `other`.

 |
| `building_iri` | string | Yes | 

A building of this organization (full IRI).

 |
| `currency` | string | No | 

Three letters, trimmed and upper-cased. Omit or `null`: a POST stores the organization's default currency (CAD when it has none) and a PUT keeps the stored one.

 |
| `note` | string | No | 

At most 1000 characters; blank is stored as `null`.

 |
| `valued_on` | string | Yes | 

`YYYY-MM-DD`, not after today. One value per building per date.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Updated. An omitted or null currency keeps the stored one |
| 400 | Same validation as POST |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify property values, or either the stored or the new building is outside your granted Financial write scope |
| 404 | No property value with this id in your organization |
| 409 | This building already has a value recorded on that date |
| 500 | Error reading the graph or writing the value |

DELETE `/property-values/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
property value id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify property values, or the stored value's building is outside your granted Financial write scope |
| 404 | No property value with this id in your organization |
| 500 | Error reading the graph or deleting the value |

## Spaces and equipment (17)

GET `/equipment`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `building` | query | No | string.
Restrict to one building, a database id or a full building IRI.

 |
| `month` | query | No | string.

Reporting month (`YYYY-MM`), see \[`EquipmentInfo::status_as_of`\].

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Equipment (optionally scoped to one building, optionally with each item's status as of a reporting month) |
| 400 | `building` given but not a valid id/IRI, or `month` given but not a valid YYYY-MM |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the equipment listing or the caller's granted scope |

POST `/equipment`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/equipment`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_tag` | string | No | 
`rec:assetTag`, verbatim.

 |
| `commissioned_by` | string | No | 

`rec:commissionedBy`, a plain contractor/vendor name, not an `rec:Agent` graph node; see `gk_ingest::connectors::REC_COMMISSIONED_BY`'s own doc comment for why.

 |
| `commissioning_date` | string | No | 

`rec:commissioningDate`, an ISO `YYYY-MM-DD` date string.

 |
| `equipment_class` | string | No | 

g. `"AHU"`, `"Chiller"`, `"VAV"`), see `gk_ingest::connectors::equipment_brick_class` for the full curated list.

 |
| `label` | string | Yes |  |
| `location_iri` | string | No | 

The building/site/space this equipment is `rec:locatedIn`, if any, an unattached piece of equipment is legal, and there is no Portfolio-stub fallback.

 |
| `maintenance_interval_days` | integer | No | 

Whole days between scheduled maintenance, `rec:maintenanceInterval`, formatted server-side as its `xsd:duration` lexical form.

 |
| `part_of_iri` | string | No | 

g. a fan inside an AHU), composition, independent of `location_iri`'s physical placement. Must name an in-org `/equipment/` IRI.

 |
| `status` | string | No | 

Operational lifecycle status, one of `gk_ingest::connectors::EQUIPMENT_STATUSES`. `gk:equipmentStatus`.

 |
| `status_note` | string | No | 

A free-text note on why `status` is what it is, recorded alongside this status in `equipment_status_history`, ignored when `status` is absent (there is no transition to attach it to).

 |
| `warranty_end_date` | string | No | 

`gk:warrantyEndDate`, the last day under warranty, an ISO `YYYY-MM-DD` date string. Shown on the organization calendar.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Equipment created and its provenance-carrying ingest job committed |
| 400 | Empty/oversize label, a location\_iri outside this org or naming a Collection (portfolio/campus), an unrecognized equipment\_class, or a part\_of\_iri outside this org or not naming an equipment item |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Database or ingest error |

PATCH `/equipment`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Request body

application/json, required.

iri=<encoded>`.`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_tag` | string | No | 
`rec:assetTag`, same absent/null/value contract.

 |
| `commissioned_by` | string | No | 

`rec:commissionedBy`, same absent/null/value contract.

 |
| `commissioning_date` | string | No | 

`rec:commissioningDate` (`YYYY-MM-DD`), same absent/null/value contract.

 |
| `feeds_iris` | list of string | No | 

`brick:feeds`, the equipment in the same building this item supplies (an air handler feeding VAV boxes). Absent leaves the links alone, a list REPLACES them, `[]` clears them. Refused together with `location_iri`: the same-building check reads where the item is now.

 |
| `label` | string | No |  |
| `location_iri` | string | No | 

`null` detaches the equipment, a string relocates it, absent leaves it alone. `skip_serializing_if` is load-bearing here too, see `UpdateSpaceRequest::gross_area`'s comment.

 |
| `maintenance_interval_days` | integer | No | 

`rec:maintenanceInterval`, as a whole day count, same absent/null/ value contract.

 |
| `status` | string | No | 

`gk:equipmentStatus`, same absent/null/value contract as `location_iri`. `null` clears it, a value (must be one of `gk_ingest::connectors::EQUIPMENT_STATUSES`) replaces it.

 |
| `status_note` | string | No | 

A free-text note on why `status` is what it is, recorded alongside this edit in `equipment_status_history`, ignored when `status` is absent from the SAME request (there is no transition to attach it to). Plain, not clearable: a history row is append-only, so there is no existing note to clear.

 |
| `warranty_end_date` | string | No | 

`gk:warrantyEndDate` (`YYYY-MM-DD`), same absent/null/value contract.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Equipment updated and its provenance-carrying ingest job committed |
| 400 | No fields to update, an invalid field value, iri outside this org, location\_iri outside this org or naming a Collection, feeds\_iris sent with location\_iri, a new feeds\_iris target that is not equipment in the same building (or is the item itself, or already feeds it), or location\_iri/feeds\_iris sent for a meter, or the change was refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered; the item or a new feeds\_iris target is outside your granted write scope; or the save drops a feed link you can see but not change |
| 404 | iri does not exist in this org's graph, or does not name equipment or a meter |
| 500 | Database or ingest error |

DELETE `/equipment`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Equipment deleted |
| 400 | iri outside this org, or the delete was refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | iri does not exist in this org's graph, or does not name equipment |
| 409 | The equipment is synced from a provider, so a delete would last only until the next sync recreates it |
| 500 | Database or ingest error |

GET `/equipment/status-history`month=\` reads on \`GET /api/v1/equipment\` cannot answer (those reduce to a single instant each).

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every recorded status transition for this equipment item, newest first |
| 400 | iri outside this org |
| 401 | Not authenticated |
| 403 | User not registered, or this entity is outside your granted read scope |
| 404 | iri does not exist in this org's graph, or does not name a meter or an equipment item |
| 500 | Database or ingest error |

POST `/spaces`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/spaces`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address_line1` | string | No | 
The 6 `rec:PostalAddress` fields, named after `rec:PostalAddress`'s own properties. Meaningful for `kind = "building"`/`"site"` only (mirrors `jurisdiction`'s own eligibility), ignored for every other kind.

 |
| `address_line2` | string | No |  |
| `city` | string | No |  |
| `country` | string | No |  |
| `gross_area` | number | No |  |
| `gross_area_unit` | string | No | 

Unit `gross_area` was reported in, `"ft2"`/`"m2"` (any spelling `gk_ingest::connectors::area_unit_iri` resolves).

 |
| `gross_building_area` | number | No | 

`gk:grossBuildingArea`, BOMA's Gross Building Area. Same eligibility and `gross_area_unit` sharing as `gross_area`.

 |
| `gross_leasable_area` | number | No | 

`gk:grossLeasableArea`, BOMA/ICSC's Gross Leasable Area, alongside `gross_area`'s Gross Floor Area. Same eligibility and `gross_area_unit` sharing as `gross_area`.

 |
| `jurisdiction` | string | No |  |
| `kind` | string | Yes | 

One of `site`/`building`/`floor`/`space`/`room`/`campus`/`region`, `meter` and `equipment` have their own endpoints (`POST /api/v1/meters`, `POST /api/v1/equipment`).

 |
| `label` | string | Yes |  |
| `parent_iri` | string | No |  |
| `postal_code` | string | No |  |
| `region` | string | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Entity created and its provenance-carrying ingest job committed. A building past its organization's GK\_GEOCODE\_DAILY\_LIMIT address lookups for today is still created, without a lookup, and `notice` says so |
| 400 | Unknown kind, empty/oversize label, a parent\_iri outside this org, or a building with no province or state (give `region`, or a `jurisdiction` such as CA-ON; the answer says what to add) |
| 401 | Not authenticated |
| 402 | A building past the Free plan's limit (`error`: free\_plan\_building\_limit, `message` says what to do) |
| 403 | User not registered, or (`error`: building\_read\_only) the parent is a read-only building |
| 500 | Database or ingest error |

PATCH `/spaces`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Request body

application/json, required.

iri=<encoded>`. Only fields present in the JSON change; see the module doc for the absent/null/value convention on` gross\_area`/`jurisdiction`.`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `address_line1` | string | No | 
The `rec:PostalAddress` fields, same names as `POST /api/v1/spaces`. Building or site only. Each is absent (leave alone), `null` (clear) or a value; `address_line1` may not be blank. A changed address queues one new address lookup and keeps the old map pin until it answers.

 |
| `address_line2` | string | No |  |
| `chilled_water_generation_method` | string | No | 

`gk:chilledWaterGenerationMethod` -- same absent/null/value contract as `jurisdiction`.

 |
| `city` | string | No |  |
| `country` | string | No |  |
| `gross_area` | number | No |  |
| `gross_area_unit` | string | No | 

Independent of `gross_area` (same absent/null/value contract) so a mislabeled unit can be corrected without re-entering the value.

 |
| `gross_building_area` | number | No | 

`gk:grossBuildingArea`, same absent/null/value contract as `gross_area`, and shares its `gross_area_unit`.

 |
| `gross_leasable_area` | number | No | 

`gk:grossLeasableArea`, same absent/null/value contract as `gross_area`, and shares its `gross_area_unit`.

 |
| `jurisdiction` | string | No |  |
| `label` | string | No |  |
| `postal_code` | string | No |  |
| `region` | string | No |  |
| `valid_from` | string | No | 

The day an edited gross area starts to hold (`YYYY-MM-DD`), kept in the building's fact history. Omitted means now. Any past day is allowed, a day after today is a 400.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Entity updated and its provenance-carrying ingest job committed. After an address edit whose map lookup could not be queued (no lookup service, the day's lookups spent, a read that failed), `notice` says what happened and what to do next |
| 400 | No fields to update, an invalid field value, iri outside this org, jurisdiction or an address on a non-building/site kind, an address edit that leaves a building with no province or state (the answer says what to add), an address\_line1 that is blank, chilled\_water\_generation\_method on a non-building kind, or the change was refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | iri does not exist in this org's graph, or names a different kind of entity |
| 500 | Database or ingest error |

DELETE `/spaces`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Entity deleted |
| 400 | iri outside this org, the entity has children (move or delete them first), or the delete was refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | iri does not exist in this org's graph, or names a different kind of entity |
| 409 | The record is synced from a provider such as ENERGY STAR, so a delete would last only until the next sync recreates it |
| 500 | Database or ingest error |

GET `/spaces/address`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The node's rec:address parts; all null when it has none |
| 400 | iri outside this org |
| 401 | Not authenticated |
| 403 | User not registered, or not allowed to edit this space |

GET `/spaces/area`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The node's own rec:grossArea/gk:grossLeasableArea/gk:grossBuildingArea/gk:areaUnit, unconverted |
| 400 | iri outside this org |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/spaces/campus`

Token that can change data

#### Request body

application/json, required.

`POST /api/v1/spaces/campus` body.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `initial_member` | object | Yes | 
Body of `POST /api/v1/spaces`.

 |
| `initial_member.address_line1` | string | No | 

The 6 `rec:PostalAddress` fields, named after `rec:PostalAddress`'s own properties. Meaningful for `kind = "building"`/`"site"` only (mirrors `jurisdiction`'s own eligibility), ignored for every other kind.

 |
| `initial_member.address_line2` | string | No |  |
| `initial_member.city` | string | No |  |
| `initial_member.country` | string | No |  |
| `initial_member.gross_area` | number | No |  |
| `initial_member.gross_area_unit` | string | No | 

Unit `gross_area` was reported in, `"ft2"`/`"m2"` (any spelling `gk_ingest::connectors::area_unit_iri` resolves).

 |
| `initial_member.gross_building_area` | number | No | 

`gk:grossBuildingArea`, BOMA's Gross Building Area. Same eligibility and `gross_area_unit` sharing as `gross_area`.

 |
| `initial_member.gross_leasable_area` | number | No | 

`gk:grossLeasableArea`, BOMA/ICSC's Gross Leasable Area, alongside `gross_area`'s Gross Floor Area. Same eligibility and `gross_area_unit` sharing as `gross_area`.

 |
| `initial_member.jurisdiction` | string | No |  |
| `initial_member.kind` | string | Yes | 

One of `site`/`building`/`floor`/`space`/`room`/`campus`/`region`, `meter` and `equipment` have their own endpoints (`POST /api/v1/meters`, `POST /api/v1/equipment`).

 |
| `initial_member.label` | string | Yes |  |
| `initial_member.parent_iri` | string | No |  |
| `initial_member.postal_code` | string | No |  |
| `initial_member.region` | string | No |  |
| `label` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Campus and its first member created together in one ingest job |
| 400 | kind is not building/site, an empty/oversize label, or a parent\_iri outside this org |
| 401 | Not authenticated |
| 402 | The first member is a building past the Free plan's limit (`error`: free\_plan\_building\_limit, `message` says what to do) |
| 403 | User not registered, or not an org-wide writer |
| 500 | Database or ingest error |

GET `/spaces/occupant`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Who occupies the space (our organization, a tenant from the building's leases, or nobody marked) and the building's tenants to choose from |
| 400 | Invalid iri, or an iri outside this organization |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings and does not include this one |
| 500 | Reading the graph, the leases or the occupant failed |

PUT `/spaces/occupant`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Request body

application/json, required.

iri=`.`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `lease_id` | integer | No | 
Required for `tenant`: a lease of the building this space sits in.

 |
| `occupant` | string | Yes | 

`none`, `us` or `tenant`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The occupant as it now stands |
| 400 | Invalid iri or occupant, a kind that cannot carry an occupant, a missing lease\_id, or a lease of another building |
| 401 | Not authenticated |
| 403 | Only owners and admins can change organization settings |
| 404 | iri does not exist in this org's graph |
| 409 | Our organization already occupies a space above or below this one |
| 500 | Reading the graph or writing the occupant failed |

GET `/spaces/occupied`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every space this organization has marked as occupied, with when a person marked it |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings and does not include this one |
| 500 | Error reading the marks |

PUT `/spaces/occupied`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Request body

application/json, required.

iri=<space>`.`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `occupied` | boolean | Yes | 
`true` marks the space as occupied by this organization; `false` clears the mark. REQUIRED, omitting it is a decode error, never a silent unmark.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The mark as it now stands |
| 400 | Invalid iri, iri outside this org, or a kind that cannot carry a mark (building/site/campus/region/portfolio, meter, equipment) |
| 401 | Not authenticated |
| 403 | Only owners and admins can change organization settings |
| 404 | iri does not exist in this org's graph |
| 409 | Another mark already sits on this space's containment line, above or below it |
| 500 | Error reading the graph or writing the mark |

POST `/spaces/reparent`Its own endpoint rather than a \`PATCH /api/v1/spaces\` field because a containment change is dual-sided, the old parent's edge must go and the new parent's edge must land, and the PREDICATE AND DIRECTION differ per kind pairing (\`floor rec:isPartOf building\` vs \`campus rec:includes building\`), so the ops can only be built after three graph reads (child kind, current edge, cycle check) that the deliberately DB-free op-builders must not do.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Request body

application/json, required.

Body of `POST /api/v1/spaces/reparent`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `new_parent_iri` | string | Yes | 
The new parent's graph IRI.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Entity re-parented; both containment edges changed in one job |
| 400 | Invalid kind pairing, would create a containment cycle, already the parent, iri outside this org, or refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | iri does not exist in this org's graph, or names a different kind of entity |
| 409 | The entity carries more than one containment edge, a data anomaly this endpoint refuses to compound |
| 500 | Database or ingest error |

GET `/spaces/tree`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Org's site/building/floor/space hierarchy, nested. Each node below the roots carries its own gross\_area and gross\_area\_unit (ft2 or m2) when recorded, otherwise null, for every reader |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |
| 500 | The graph store did not answer the space tree read |

## Meters and readings (31)

GET `/data-coverage`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `from` | query | Yes | string.
First day, inclusive, `YYYY-MM-DD`.

 |
| `to` | query | Yes | string.

Day after the last, exclusive, `YYYY-MM-DD`. Whole UTC months are counted, up to 60.

 |
| `gap` | query | No | string.

Narrow the building rows only (never the columns or the tiles): `bills`, `area`, `emissions`, `unattached` or `unread`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | For the whole portfolio the caller may read: four tile counts, and per building the bill months received of months due for each fuel, the floor area (entered, a stand-in from the space around it, or missing), the emissions inputs missing, the meters, the gaps with the words of their fix buttons, and a status (Complete, gaps, or Could not be read). One row lists the meters in no building. A building whose data could not be read is never Complete. With gap, only the rows that have that gap. |
| 400 | The dates are missing or out of order, the span is over 60 months, or gap is not one of bills, area, emissions, unattached, unread |
| 401 | Not authenticated |
| 403 | A person limited to some buildings with no Energy, Data sources or Sustainability access |
| 500 | A read failed; nothing partial is returned |

GET `/meter-matches`The org's proposed cross-source meter matches, newest first.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `status` | query | No | string.
`open` (default), `confirmed`, or `dismissed`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Proposed matches in the requested status |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings and does not include meter matches |

POST `/meter-matches/{id}/confirm`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Request body

application/json, required.

Body of `POST /api/v1/meter-matches/{id}/confirm`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `kept_meter_iri` | string | Yes | 
Must equal `meter_a_iri` or `meter_b_iri` on the row.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Match confirmed; the excluded meter is now excluded from every registered calculation module |
| 400 | kept\_meter\_iri is neither meter\_a\_iri nor meter\_b\_iri on this row |
| 401 | Not authenticated |
| 403 | Only owners/admins/editors, org-wide |
| 404 | No such proposed match in this org |
| 409 | The proposed match is not open |

POST `/meter-matches/{id}/dismiss`Dismiss a proposed match: the two meters are NOT the same physical meter. No side effect beyond closing the row, the sweep never re-proposes a dismissed pair (\`meter\_match\_detect::plan\_meter\_matches\`'s \`already\_decided\` set).

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Proposed match dismissed |
| 401 | Not authenticated |
| 403 | Only owners/admins/editors, org-wide |
| 404 | No such proposed match in this org |
| 409 | The proposed match is not open |

POST `/meter-matches/scan`Run detection for the caller's org right now, synchronously, the "connect a feed, see proposals immediately" complement to whatever periodic sweep eventually exists.

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Detection ran; the number of proposals inserted or refreshed |
| 401 | Not authenticated |
| 403 | Only owners/admins/editors, org-wide |
| 500 | Database or graph error |

POST `/meters`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/meters`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `building_iri` | string | No | 
The building this meter is `rec:locatedIn`, if any, an unattached meter is legal, and there is no Portfolio-stub fallback.

 |
| `components` | list of object | No | 

Shorthand for a formula that only adds and takes away whole meters: `[{meter_iri, sign: "add"|"subtract"}]` becomes `meter(a) + meter(b) - meter(c)`. Send this or `formula`, not both.

 |
| `components[].meter_iri` | string | Yes | 

A meter of this organization, of the same energy type.

 |
| `components[].sign` | string | Yes | 

`"add"` or `"subtract"`.

 |
| `effective_from` | string | No | 

The first month (`YYYY-MM`) the formula is in effect; absent reaches back to the start. Only with `formula` or `components`.

 |
| `effective_to` | string | No | 

The last month (`YYYY-MM`) the formula is in effect; absent is still in effect. Only with `formula` or `components`.

 |
| `formula` | string | No | 

Makes a calculated virtual meter from a formula over meters, bills and other virtual meters: `+ - * /`, brackets, constants, `meter(id)`, `bill(id)` and `safe_div(a, b, fallback)` (grammar in `gk_core::formula`; `id` is the last part of a meter's IRI). Worked out when read, one calendar month at a time, and never stored. Needs `is_virtual: true` and a `building_iri` (where it sits), and cannot be combined with `submeter_of` or `measures_iri`.

 |
| `is_virtual` | boolean | No | 

g. an allocated share of another meter's reading).

 |
| `label` | string | Yes |  |
| `measures_iri` | string | No | 

The `brick:meters` measurement target (a building, space, campus, or portfolio), independent of `building_iri`'s physical placement.

 |
| `report_effects` | object | No | 

What the formula's amount does to each report, as `{report: effect}`: `site_eui` and `ghg`, each `leave_out`, `add_in` or `none`. A report not named has no effect. Only with `formula` or `components`.

 |
| `split_building_iris` | list of string | No | 

Required when `measures_iri` names a campus or site and the meter is not virtual: the buildings the main meter is split across. One virtual share meter is created per building, allocated by floor area.

 |
| `submeter_of` | string | No | 

g. a tenant panel submeter of a landlord main meter), if any.

 |
| `utility_type` | string | Yes | 

g. `"electric"`/`"e"`, `"gas"`/`"g"`, `"water"`/`"w"`, the alias set of `gk_ingest::connectors::meter_class`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Meter created and its provenance-carrying ingest job committed |
| 400 | Empty/oversize label, unknown utility\_type, a building\_iri outside this org or naming a Collection, a submeter\_of outside this org or not naming a meter, a measures\_iri outside this org, is\_virtual: true combined with a building\_iri, a campus or site measures\_iri without a split\_building\_iris (non-empty, distinct in-org buildings), or a split\_building\_iris on any other meter |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Database or ingest error |

PATCH `/meters`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Request body

application/json, required.

iri=<encoded>`.`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `building_iri` | string | No | 
`null` detaches the meter, a string relocates it, absent leaves it alone. `skip_serializing_if` is load-bearing here too, see `UpdateSpaceRequest::gross_area`'s comment.

 |
| `components` | list of object | No | 

Replaces the formula with a plain list of added and taken-away meters (see \[`CreateMeterRequest::components`\]). Only a calculated meter whose formula is itself such a list takes it, so an edit can never flatten a formula with multiplication or a guarded divide. Send this or `formula`.

 |
| `components[].meter_iri` | string | Yes | 

A meter of this organization, of the same energy type.

 |
| `components[].sign` | string | Yes | 

`"add"` or `"subtract"`.

 |
| `effective_from` | string | No | 

With `formula` or `components`: the first month (`YYYY-MM`) the new formula is in effect. The formula in effect before ends the month before and stays on record, so the months before keep their old totals. Absent means this month.

 |
| `effective_to` | string | No | 

With `formula` or `components`: the last month (`YYYY-MM`) the new formula is in effect; absent is still in effect. Refused when it would cut the formula in effect before in two.

 |
| `ends_after` | string | No | 

Ends the formula that is still in effect after this month (`YYYY-MM`): later months have no value until a new formula starts. Send it alone.

 |
| `formula` | string | No | 

Replaces the formula of a calculated virtual meter (see \[`CreateMeterRequest::formula`\]). Absent leaves it alone. Only a meter created with a formula takes it.

 |
| `label` | string | No |  |
| `report_effects` | object | No | 

What the formula's amount does to each report, as `{report: effect}` (`site_eui` and `ghg`; `leave_out`, `add_in` or `none`). It belongs to the formula rule, so a change starts a new rule like a new formula does (from `effective_from`, else this month). Sent alone it keeps the formula in effect and changes only the reports named; sent with a new formula, a report not named keeps the effect the rule it replaces had.

 |
| `submeter_of` | string | No | 

The meter this one is a sub-meter of (`brick:isSubMeterOf`): a meter IRI sets or replaces it, `null` clears it, absent leaves it alone.

 |
| `utility_account_number` | string | No | 

The utility account the meter is billed under (`gk:utilityAccountNumber`), same absent/null/value contract as `utility_meter_number`. Several meters may share an account, so it has no duplicate check.

 |
| `utility_meter_number` | string | No | 

The meter number the utility prints on its bills (`gk:utilityMeterNumber`): a string sets it, `null` clears it, absent leaves it alone. Another meter of the organization already carrying the same number answers 409 naming that meter. Who entered it is recorded with the edit, like every hand-entered fact.

 |
| `utility_type` | string | No | 

). Absent leaves it alone. Only a meter created through `POST /api/v1/meters` can change it: a bill or a connector sets its own meters' type again on its next upload.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Meter updated and its provenance-carrying ingest job committed |
| 400 | No fields to update, an invalid field value, iri outside this org, building\_iri outside this org or naming a Collection, an unknown utility\_type, an energy-type change on a meter a bill or connector created or on one with a parent or sub-meters, a submeter\_of that is not a physical meter of this org, is the meter itself, has another energy type or would make a loop, or the change was refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered, or the meter or its new parent meter is outside your granted write scope |
| 404 | iri does not exist in this org's graph, or does not name a meter |
| 409 | utility\_meter\_number is already on another meter of this organization; the message names that meter |
| 500 | Database or ingest error |

DELETE `/meters`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Meter deleted |
| 400 | iri outside this org, or the delete was refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | iri does not exist in this org's graph, or does not name a meter |
| 409 | The meter is synced from a provider, so a delete would last only until the next sync recreates it, or a calculated virtual meter is built from it |
| 500 | Database or ingest error |

GET `/meters/billed-monthly`Whether one meter is marked as billed monthly.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The meter's IRI, as the meters read gives it.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The meter's answer; false when nobody has answered |
| 400 | `iri` is not a valid IRI |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings and does not include this meter |
| 500 | Reading the setting failed |

PUT `/meters/billed-monthly`Marks one meter as billed monthly, or as not.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The meter's IRI, as the meters read gives it.

 |

#### Request body

application/json, required.

Body of `PUT /api/v1/meters/billed-monthly`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `billed_monthly` | boolean | No | 
Older callers: true is the same as `data_interval: "monthly"`, false says the meter is not billed on a schedule. Ignored when `data_interval` is given. Clearing the answer altogether is `DELETE`.

 |
| `data_interval` | string | No | One of: fifteen\_minute, hourly, daily, monthly, bimonthly, quarterly, annual.

How often a meter's data arrives. The wire and column spelling is `as_str`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Saved; the meter's answer |
| 400 | Neither `data_interval` nor `billed_monthly` is given, `iri` is not a valid IRI, is not a meter of this organization's graph, or is a meter whose class does not say which utility it bills (an unclassified meter), so no Energy or Water tab could show it |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or is limited to specific buildings |
| 500 | Reading the graph or saving the setting failed |

DELETE `/meters/billed-monthly`Forgets a meter's answer, back to "not said".

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The meter's IRI, as the meters read gives it.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 204 | Cleared (also when there was nothing to clear) |
| 400 | `iri` is not a valid IRI |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or is limited to specific buildings |
| 500 | Clearing the setting failed |

GET `/meters/calculated`A calculated virtual meter's formula and its value for each of the last twelve complete calendar months, worked out when asked (virtual meters in dependency order) and stored nowhere. A month where a piece has no reading has no value and says which, never a zero; a negative value is shown and marked, never floored.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `iri` | query | Yes | string.
The target entity's full IRI, URL-encoded.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The meter's formula and monthly values |
| 400 | iri outside this org |
| 401 | Not authenticated |
| 403 | The meter is outside your granted read scope |
| 404 | iri does not exist, is not a meter, or is not a calculated virtual meter |
| 500 | Database or graph error |

GET `/meters/unattached`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Meters attached to nothing (no location edge, no brick:meters target), counted in no building until attached, then the meters placed somewhere that still count in no building, each with its no\_building\_reason |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered, or limited to specific buildings and holding no grant for energy |
| 500 | The graph store did not answer the unattached-meter listing |

GET `/reading-conflicts`The organization's reading conflicts with one status, newest first, each naming both values and where each came from.

Any API token

Cost: ONE statement (`reading_conflict_org_status`, plus primary-key probes per returned row for the two jobs, the person and the stored reading), and two graph reads for the labels only when a row came back.

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `status` | query | No | string.
`open` (default), `kept_recorded`, `took_proposed` or `superseded`.

 |
| `limit` | query | No | integer (int64).

At most this many rows, newest first (default 200, at most 1000).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The conflicts with the requested status, newest first. A value from an upload that never finished is not listed. A role limited to specific buildings sees only the periods of meters it has write access to. |
| 400 | An unknown status ("status must be one of open, kept\_recorded, took\_proposed, superseded") |
| 401 | Not authenticated (no session and no valid API token) |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or a role limited to specific buildings with no write access to any meter |
| 500 | Reading the conflicts failed |

POST `/reading-conflicts/{id}/resolve`Settles one reading conflict: \`replace\` makes the new value the saved reading and its period's bill agree with it; \`keep\` keeps the saved one.

Token that can change data

Someone with edit rights (owner, admin, editor) chooses, under the pipeline's org commit lock so no import judges the same period meanwhile. ONE transaction: the row is locked and checked against what the person saw (the same new value, from an upload that finished, against the same saved value), the reading replaced in place, the period's saved bills retired (position-only tombstones, so the next sync is never blocked), the row closed and the choice audited (\[`settle_in_tx`\]). After it commits and the lock is released, a replace lands the new value's own bill for that period, if its import emitted one, and nothing else.

Cost: three to seven statements in one transaction under the org lock (an import of the same organization waits milliseconds), plus for `replace` one parse of the new value's import to land its bill. Human-driven, rare.

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The reading conflict's id

 |

#### Request body

application/json, required.

Body of `POST /api/v1/reading-conflicts/{id}/resolve`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `candidate_job_id` | integer | Yes | 
job\_id`), so a choice never acts on a value that arrived after the list loaded.`

 |
| `choice` | string | Yes | 

`replace` makes the new value the saved reading; `keep` keeps the saved one.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Settled: the row is `took_proposed` or `kept_recorded` |
| 400 | An unknown choice ("choice must be \\"replace\\" or \\"keep\\""); nothing changed |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered; a role that cannot edit; or a role limited to specific buildings choosing for a meter outside its granted write scope |
| 404 | No such reading conflict in this organization |
| 409 | Nothing was chosen: the conflict was already settled or a newer value superseded it; the upload of the new value did not finish; the saved or new value changed since the list loaded (the row now shows what is saved); or another reading of the meter already holds that period or carries that source record; or the new value is a workbook reading and the building rename has not finished. The body says which and what to do. |
| 500 | Saving the choice failed and nothing changed; or the new value is saved but its bill could not be added (the body says so) |

GET `/series`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `meter_key` | query | No | string.
Look up the series by its ingest-time meter key (see `gk_ingest::connectors::meter_key`). Ignored when `series_id` or `series_ids` is set.

 |
| `series_id` | query | No | integer (int64).

id`. Ignored when` series\_ids `is set.`

 |
| `series_ids` | query | No | string. |
| `include` | query | No | string.

`measured_only`: the series list also carries the series a contractor sees only because their meter measures a granted entity, each flagged `measured_only`. Without it the list holds only the caller's own series. Any other value is a 400. The by-id and `meter_key` reads need no opt-in.

 |
| `start` | query | No | string (date-time).

Inclusive lower bound, RFC 3339.

 |
| `end` | query | No | string (date-time).

Exclusive upper bound, RFC 3339.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Neither meter\_key nor series\_id/series\_ids given: the org's series list, without extra reading series (demand, reactive energy, reverse flow, a second copy of the energy), which a series\_ids or meter\_key lookup still returns |
| 400 | Malformed, empty, or over-limit series\_ids |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such series in this org |

GET `/series/{id}/corrections`What sources replaced on one meter's readings, newest first.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The series id

 |
| `from` | query | No | string (date-time).

Only readings whose period starts at or after this time (RFC 3339). Meters only.

 |
| `to` | query | No | string (date-time).

Only readings whose period starts at or before this time (RFC 3339). Meters only.

 |
| `limit` | query | No | integer (int64).

Corrections per page, 1 to 500; 100 when absent.

 |
| `offset` | query | No | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The values a source replaced on this meter's readings, newest first, with the source and time; cost is left out without the Financial grant |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 404 | No such series in your organization, or one your role cannot read |
| 500 | Reading the history failed |

GET `/series/{id}/load-profile`Peak demand, peak day and hour, load factor and the average day from one interval series.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The series id

 |
| `start` | query | No | string (date-time).

Inclusive start (RFC 3339); 365 days before `end` when absent.

 |
| `end` | query | No | string (date-time).

Exclusive end (RFC 3339); just after the latest reading when absent.

 |
| `tz` | query | No | string.

The IANA time zone hours and days are counted in; `America/Toronto` when absent.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The demand the series' readings show over the window, computed fresh (never stored). `not_available` says why when the readings cannot show demand (not interval data, a unit that is not energy or power, no readings) |
| 400 | `end` is not after `start`, the window is longer than 366 days, or `tz` is not a time zone |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 404 | No such series in your organization, or one your role cannot read |
| 500 | Reading the readings failed |

GET `/series/{id}/reading-series`The meter a series belongs to, and its usage, demand, energy sent to the grid and other series.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The series id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The meter behind the series and every series of that meter the caller may read: its own first, then its extra kinds of reading |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 404 | No such series in your organization, or one your role cannot read |
| 500 | Reading the meter or its series failed |

GET `/series/{id}/readings`A meter's readings one page at a time, newest first, each with where it came from.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The series id

 |
| `before` | query | No | string (date-time).

Only readings strictly before this time (RFC 3339): the `next_before` of the previous page.

 |
| `limit` | query | No | integer (int64).

Readings per page, 1 to 500; 100 when absent.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | One page of readings, newest first, each with its source import (`recorded` with the reading, or `bill`: the import of the bill for the same period); `next_before` pages back |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 404 | No such series in your organization, or one your role cannot read |
| 500 | Reading the readings failed |

GET `/series/{id}/unit`A series' billed unit, and who changed it before.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The series id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The unit now and every change made to it, newest first |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings and does not include this meter |
| 404 | No such series in your organization |
| 500 | Reading the unit failed |

PUT `/series/{id}/unit`Corrects a meter's billed unit. The readings keep their numbers; the old unit is kept with who changed it and when.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The series id

 |

#### Request body

application/json, required.

Body of `PUT /api/v1/series/{id}/unit`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | Yes | 
The unit the person saw when they opened the meter. The change is refused with a 409 when the meter has another unit by now, so two people cannot overwrite each other unseen.

 |
| `unit` | string | Yes | 

The unit to give the meter: a spelling BrickFlow can convert (an energy, volume or mass unit), such as `therms` or `kcf`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Changed; the unit now and its history |
| 400 | The unit is empty or too long, is not one BrickFlow can convert, is an area, is the contested 'Mcf', is already the meter's unit, or the meter is stored in gallons or litres, which BrickFlow cannot convert yet |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or is limited to specific buildings |
| 404 | No such series in your organization |
| 409 | The meter's unit is no longer `from`: someone changed it since it was opened |
| 500 | Saving the change failed |

POST `/series/{id}/unit/preview`Previews a unit change.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The series id

 |

#### Request body

application/json, required.

Body of `POST /api/v1/series/{id}/unit/preview`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `unit` | string | Yes | 
The unit the person is about to give the meter; checked exactly as the change checks it.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The years the meter has readings in and every Site EUI and emissions total, and the meter's own yearly energy in kWh, that the change would move; nothing is written |
| 400 | The unit is empty or too long, is not one BrickFlow can convert, is an area, is the contested 'Mcf', is already the meter's unit, or the meter is stored in gallons or litres, which BrickFlow cannot convert yet |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or is limited to specific buildings |
| 404 | No such series in your organization |
| 500 | Computing the preview failed |

GET `/series/areas`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Each readable series' spaces and their floor areas |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | The graph or the building links could not be read |

GET `/series/intervals`How far apart the latest readings of each listed series are.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `series_ids` | query | Yes | string.
Comma-separated series ids, at most 200.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Per requested series the caller may read: the usual gap between its latest readings and whether it is interval data that can show demand. A series the caller cannot read, or that is not the organization's, is left out |
| 400 | Malformed, empty, or more than 200 series ids |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 500 | Reading the readings failed |

GET `/series/monthly-digest`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `series_ids` | query | Yes | string.
series\_ids=`.`

 |
| `windows` | query | Yes | string.

Comma-separated windows, each `start/end` in RFC 3339 at midnight UTC, a window being `[start, end)`; one to four. The response gives each series one month list per window, in this order.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | For each requested series the caller may read, in request order: per window, its UTC calendar months with the count, sum, sign counts, sizes, day counts and (when at most five) the values of its readings, and the same per currency for its costs. An id of another organization, or one the caller may not read, is absent. |
| 400 | Malformed, empty, or over-limit series\_ids or windows |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | The readings could not be read |

GET `/series/provenance`The readings and bills behind a tile's number, each with where it came from.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `series_ids` | query | Yes | string.
Comma-separated series ids (the same limit as `GET /api/v1/series`).

 |
| `from` | query | Yes | string (date-time).

Periods starting at or after this time (RFC 3339).

 |
| `to` | query | Yes | string (date-time).

Periods starting before this time (RFC 3339).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Per requested series, in the caller's order: its readings and bills whose period starts in the window, each with the import it came from, the source's own id and quality mark; cost and currency only with the Financial grant |
| 400 | Malformed or over-limit series\_ids, or a window that ends before it starts |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 404 | A named series is not in your organization, or is one your role cannot read |
| 500 | Reading the readings failed |

GET `/unit-interpretations`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every resolved spelling for the org |
| 401 | Not authenticated |
| 403 | User not registered |

PUT `/unit-interpretations`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fuel` | string | Yes |  |
| `resolved_unit` | string | Yes |  |
| `unit` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 204 | Interpretation saved |
| 400 | Malformed unit, fuel or resolved\_unit |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

DELETE `/unit-interpretations/{fuel}/{unit}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `fuel` | path | Yes | string. |
| `unit` | path | Yes | string. |

#### Replies

| Status | Meaning |
| --- | --- |
| 204 | Interpretation cleared; the reading reverts to excluded |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

GET `/weather/bills`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `ids` | query | Yes | string.
Comma-separated bill (`utility_invoice`) ids, at most 500.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Degree days for each of the organization's requested bills, in the order asked; bills the organization does not own are absent |
| 400 | `ids` is empty, has an entry that is not a whole number, or names more than 500 bills |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 500 | Reading the bills, buildings or weather failed |

## Bills (27)

GET `/discrepancies`The org's flagged cross-source conflicts, newest first.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `status` | query | No | string.
`open` (default), `resolved_incumbent`, `resolved_candidate`, or `dismissed`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Flagged conflicts in the requested status |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/discrepancies/{id}/resolve`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Request body

application/json, required.

Body of `POST /api/v1/discrepancies/{id}/resolve`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `choice` | string | Yes | 
`incumbent` keeps what the graph records; `candidate` replaces it with the source's proposed value.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Conflict resolved |
| 400 | Unknown choice, or applying the candidate was refused by the data-quality rulebook (JSON EditRefusal body) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such discrepancy in this org |
| 409 | The discrepancy is not open (already resolved or dismissed) |
| 500 | Database or ingest error |

GET `/facility-bills`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `category` | query | No | string.
Filter to one bill category ("Facilities/Equipment" or "Services/Other"); omit for both

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | This organization's non-metered bills, newest service period first |
| 400 | An unknown category filter |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings |

POST `/facility-bills`

Token that can change data

#### Request body

application/json, required. list of object

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created |
| 400 | Empty or oversized submission, a category outside the two non-metered branches, a blank vendor/description, an inverted service period, a negative cost, or a building\_iri that is not an existing building in this organization |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings |

GET `/facility-bills/{id}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
facility\_bill id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | One bill |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings |
| 404 | No bill with this id in your organization |

GET `/fx/rates`

Any API token, also Read reports only

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `currencies` | query | No | string.
Comma-separated ISO 4217 codes, 1 to 30, each three capital letters. `CAD` is allowed and answered as 1.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Monthly and yearly average rates for the asked currencies; CAD is answered as 1 for every month and year stored |
| 400 | `currencies` is missing, empty, names more than 30 codes, or has an entry that is not three capital letters |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 500 | Reading the stored rates failed |

GET `/invoices/charges`What each meter's bills charged for, per month.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `start` | query | Yes | string (date-time).
Inclusive, RFC 3339.

 |
| `end` | query | Yes | string (date-time).

Exclusive, RFC 3339.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Per meter, UTC month of the bill start and currency: the bills counted, their total and the total split by charge |
| 400 | `start` or `end` is missing or not RFC 3339, or `start` is not before `end` |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered |
| 500 | Reading the bills, or a scoped role's granted series, failed |

GET `/invoices/coverage`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `from` | query | No | integer (int64).
Inclusive lower bound on a bill's `end_date` (epoch seconds) for the periods returned; meter identity and `first_start` always read the whole history.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every meter of the organization with its latest bill's identity, first period start and the periods ending at or after `from`, plus the full rows of the bills whose meter resolves to no building |
| 400 | `from` is not a whole number |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or lacks org-wide read access |
| 500 | Reading the bills or the meters' building attribution failed |

GET `/invoices/demand`Every bill of the organization that carries a demand reading, newest first.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every bill whose `demand` text is not blank, newest first, each with the meter it derives and whether that meter resolves to a building |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or lacks org-wide read access |
| 500 | Reading the bills or the meters' building attribution failed |

GET `/invoices/meter-history`Every bill of one meter, newest first.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `meter_iri` | query | Yes | string.
The meter entity to read the bills of (a `meter_iri` of an invoice row).

 |
| `account_number` | query | No | string.

The `account_number` of that meter's coverage entry. With `meter_number` it lets the read go straight to the meter's bills through an index instead of first listing every spelling of every meter of the organization; the answer is the same. Ignored unless both are given.

 |
| `meter_number` | query | No | string.

The `meter_number` of that meter's coverage entry; see `account_number`. Numbers that do not belong to `meter_iri` answer an empty list.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every bill whose derived `meter_iri` equals the one asked for, newest first; an IRI that matches no bill answers an empty list |
| 400 | `meter_iri` is missing |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or lacks org-wide read access |
| 500 | Reading the bills or the meters' building attribution failed |

GET `/invoices/summary`\`GET /api/v1/invoices/summary\` (PF-002): org-wide utility invoice aggregates -- counts, the single most-recent invoice, per-utility-type and per-utility-provider breakdowns, and how many invoices are unresolved (no building-attributed meter) -- that the frontend previously computed client-side by scanning the full \`GET /api/v1/utility-invoices\` array.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Org-wide utility invoice aggregates: counts, the most-recent invoice, per-utility-type and per-utility-provider breakdowns, and how many invoices are unresolved |
| 401 | Not authenticated |
| 403 | User not registered, or lacks org-wide read access |

GET `/reconciliation/rates`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every confirmed rate for this org, with its tier/TOU schedule if any |
| 401 | Not authenticated |
| 403 | Scoped roles cannot view this org-wide report |

PUT `/reconciliation/rates`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `basis` | string | Yes |  |
| `currency` | string | Yes |  |
| `effective_from` | string | Yes | 
"YYYY-MM"

 |
| `rate` | number | Yes |  |
| `series_id` | integer | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Rate confirmed (or corrected, for the same series + effective\_from) |
| 400 | Negative rate, unrecognized basis, blank currency, or a malformed effective\_from |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

PUT `/reconciliation/rates/tiers`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `basis` | string | Yes |  |
| `currency` | string | Yes |  |
| `effective_from` | string | Yes | 
"YYYY-MM"

 |
| `series_id` | integer | Yes |  |
| `tiers` | list of object | Yes | 

A CONTIGUOUS progressive schedule starting at 0 consumption -- see \[`validate_tiers`\] for the exact shape enforced.

 |
| `tiers[].max_consumption` | number | No |  |
| `tiers[].min_consumption` | number | Yes |  |
| `tiers[].rate` | number | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Tiered rate schedule confirmed (replaces any prior tiers for this series + effective\_from) |
| 400 | Invalid basis/currency/effective\_from, or the tier list isn't a contiguous progressive schedule starting at 0 |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

PUT `/reconciliation/rates/tou`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `basis` | string | Yes |  |
| `currency` | string | Yes |  |
| `effective_from` | string | Yes | 
"YYYY-MM"

 |
| `series_id` | integer | Yes |  |
| `windows` | list of object | Yes |  |
| `windows[].days_of_week` | string | Yes | 

`"all" | "weekdays" | "weekends"`.

 |
| `windows[].end_hour` | integer | Yes | 

1-24, local clock hour (24 = midnight, end-exclusive).

 |
| `windows[].rate` | number | Yes |  |
| `windows[].start_hour` | integer | Yes | 

0-23, local clock hour.

 |
| `windows[].window_label` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Time-of-day rate schedule confirmed (replaces any prior windows for this series + effective\_from) -- SCHEMA ONLY, never evaluated by the report yet (no interval consumption data source) |
| 400 | Invalid basis/currency/effective\_from, or an invalid window |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

GET `/reconciliation/report`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `from` | query | No | string.
Inclusive lower bound on `period` (`YYYY-MM`). Absent means unbounded.

 |
| `to` | query | No | string.

Inclusive upper bound on `period` (`YYYY-MM`). Absent means unbounded.

 |
| `limit` | query | No | integer.

Page size, 1 to 20,000. Absent means 20,000, every bill the read covers.

 |
| `offset` | query | No | integer.

Bills to skip, newest first. Absent means 0.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | One page of the bills in the `from`/`to` window (both optional), newest first, OK/flagged/not-evaluated, read from at most the newest RECONCILIATION\_ROW\_CAP bills, with counts over the whole read. Read-only: opening the report mints and heals no alert; those follow a saved rate or default currency. |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings and does not include this report |
| 500 | Database error |

GET `/reconciliation/settings`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The org's default currency |
| 401 | Not authenticated |
| 403 | Scoped roles cannot view this org-wide report |

PUT `/reconciliation/settings`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `default_currency` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Default currency saved |
| 400 | Currency is not a 3-letter code |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

GET `/utility-budgets`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `building` | query | No | string.
Only this building's records (full IRI, URL-encoded).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every utility budget the caller may read, optionally of one building, newest year first within a building. A contractor sees a budget only when a Financial grant covers its building; a tenant sees none, and so does a token narrowed to buildings |
| 400 | building= is blank |
| 401 | Not authenticated (no session and no valid API token) |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | building= the answer is an empty list) |
| 500 | Error reading the budgets or the graph |

POST `/utility-budgets`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/utility-budgets` and `PUT /api/v1/utility-budgets/{id}`: the whole record, every time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | Yes | 
At least 0 (a zero budget is allowed), below 10000000000000.

 |
| `budget_year` | integer | Yes | 

2000-2100. One budget per building per year.

 |
| `building_iri` | string | Yes | 

A building of this organization (full IRI).

 |
| `currency` | string | No | 

As for \[`PropertyValueRequest::currency`\].

 |
| `note` | string | No | 

At most 1000 characters; blank is stored as `null`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created |
| 400 | A building\_iri that is not a building of this organization, a budget\_year outside 2000-2100, an amount that is negative or 10000000000000 or more, a currency that is not three letters, or a note over 1000 characters |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify utility budgets, or the building is outside your granted Financial write scope |
| 409 | This building already has a utility budget for that year |
| 500 | Error reading the graph or writing the budget |

PUT `/utility-budgets/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
utility budget id

 |

#### Request body

application/json, required.

Body of `POST /api/v1/utility-budgets` and `PUT /api/v1/utility-budgets/{id}`: the whole record, every time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | number | Yes | 
At least 0 (a zero budget is allowed), below 10000000000000.

 |
| `budget_year` | integer | Yes | 

2000-2100. One budget per building per year.

 |
| `building_iri` | string | Yes | 

A building of this organization (full IRI).

 |
| `currency` | string | No | 

As for \[`PropertyValueRequest::currency`\].

 |
| `note` | string | No | 

At most 1000 characters; blank is stored as `null`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Updated. An omitted or null currency keeps the stored one |
| 400 | Same validation as POST |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify utility budgets, or either the stored or the new building is outside your granted Financial write scope |
| 404 | No utility budget with this id in your organization |
| 409 | This building already has a utility budget for that year |
| 500 | Error reading the graph or writing the budget |

DELETE `/utility-budgets/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
utility budget id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify utility budgets, or the stored budget's building is outside your granted Financial write scope |
| 404 | No utility budget with this id in your organization |
| 500 | Error reading the graph or deleting the budget |

GET `/utility-invoices`limit\` is given.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `from` | query | No | integer (int64).
Inclusive lower bound on `end_date`.

 |
| `to` | query | No | integer (int64).

Exclusive upper bound on `start_date`.

 |
| `utility` | query | No | string.

g. `"electric"`.

 |
| `limit` | query | No | integer (int64).

Page size, 1 to 2000. Opt-in: without it the whole list comes back and no count is taken, so a reader that needs every bill (Coverage, the CSV export, peak demand) can never be handed a partial list by accident.

 |
| `offset` | query | No | integer (int64).

Bills to skip, newest first, 0 or more. Ignored without `limit`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The organization's bills, newest first, each with the meter it derives and whether that meter currently resolves to a building. With `limit`, one page of them, and the header `X-Total-Count` names how many bills match `from`, `to` and `utility` in all; without `limit` there is no such header |
| 400 | `from`, `to`, `limit` or `offset` is not a whole number, `limit` is not between 1 and 2000 ("limit must be between 1 and 2000"), or `offset` is negative ("offset must be 0 or more") |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or lacks org-wide read access |
| 500 | Reading the bills or the meters' building attribution failed |

POST `/utility-invoices`Manual invoice entry, routed through the ingestion pipeline (\`utility-invoice-manual\` connector): every submission becomes an \`ingest\_job\` with an immutable raw payload, graph provenance, and \`utility\_invoice\` rows stamped with \`ingest\_job\_id\`.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `allow_duplicate` | query | No | boolean.
Keep both: save a bill even though a bill for the same meter and period is already saved with DIFFERENT numbers. A bill identical to a saved one is refused all the same.

 |
| `replace` | query | No | boolean.

With `allow_duplicate`: this bill REPLACES the saved one, which the caller deletes right after, rather than being kept beside it. Its reading is written as chosen and is never added to the bill it replaces, so the meter never shows both while the delete is pending.

 |
| `allow_future_dated` | query | No | boolean.

Keep a bill whose billing period ends after today. Without it such a bill is refused with 409 `future_dated_bill` and nothing is saved, so a mistyped year is never saved behind the person's back.

 |
| `utc_offset_minutes` | query | No | integer (int32).

getTimezoneOffset()`); only names the period in a 409's message. Defaults to 0.`

 |

#### Request body

application/json, required. list of object

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every bill in the batch was ingested. A request with `Accept: application/json` gets the job and the bill periods it found already filled (`periods_already_filled`, up to 50; `readings_set_aside`, all) for an organization-wide role; any other request gets the text `Inserted utility invoices` |
| 302 | Redirect to `/subscription`: the caller has no organization yet, or the batch is empty |
| 400 | Malformed body, or 1000 or more bills in one batch |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | The caller's role cannot modify this organization's data |
| 409 | A bill in the batch ends after today (`future_dated_bill`; send `allow_future_dated=true` to keep them; `row` is the first such bill and `rows` names every one), or a bill in the batch is already saved for the same meter and billing period (`duplicate_bill`), and nothing was saved. `identical: true`: the same numbers, refused even with `allow_duplicate`. `identical: false`: different numbers; resend with `allow_duplicate=true` to keep both, or delete the saved bill. The body names the saved bill (`existing_id`, `existing`), every saved copy (`existing_ids`), the incoming `row` (its index, account, meter and period), every hit (`duplicates`) and a `message`. Two identical bills in the batch itself are refused the same way as `identical: true`, naming the earlier copy in `duplicate_of` (then `existing_id` is 0 and `existing_ids` empty) |
| 413 | The body is over the JSON size limit |
| 500 | Reading the session, resolving the organization, checking the saved bills or ingesting the batch failed |

DELETE `/utility-invoices/{id}`Deletes one saved bill. Owners and admins only. The bill's reading goes with it unless another bill for the same meter and period still shows it. When other bills kept for that meter and period remain (Keep both), the reading becomes the sum of the remaining bills and \`reading\_resummed\` is true. Otherwise the reading is retired first, through an undo job that a rebuild replays, and only once that has committed are the row removed, its tombstone written (so a replay of its import does not bring it back) and the audit row recorded, in one transaction. If the reading cannot be retired nothing is deleted. A bill a connected source would sync back is refused.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The bill's id

 |
| `replaced_by_job` | query | No | integer (int64).

Set by Replace: the ingest job (`job_id` of the save answer) of the bill that replaces this one. The deleted bill's values are kept as a correction history entry against it.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The bill is deleted; `retraction_job_id` names the undo job that removed its reading, or is null when no reading was removed; when other kept bills remain for that meter and period, the reading becomes their sum and `reading_resummed` is true |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or not an owner or admin ("Only owners and admins can delete a bill") |
| 404 | No bill with this id in this organization |
| 409 | Nothing was deleted: the bill comes from ENERGY STAR Portfolio Manager or another connected source whose next sync would bring it back, its reading carries this bill's numbers while another bill for the same meter and period has different ones (the body names that bill), or its reading could not be removed (the body says why) |
| 500 | Reading the bill or its reading, running the undo job, or deleting the row failed; a repeat is safe |

GET `/utility-invoices/{id}/corrections`What sources replaced on one bill, newest first.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The bill's record ID

 |
| `from` | query | No | string (date-time).

Only readings whose period starts at or after this time (RFC 3339). Meters only.

 |
| `to` | query | No | string (date-time).

Only readings whose period starts at or before this time (RFC 3339). Meters only.

 |
| `limit` | query | No | integer (int64).

Corrections per page, 1 to 500; 100 when absent.

 |
| `offset` | query | No | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The values a source replaced on this bill, newest first, with the source and time; money is left out without the Financial grant. An empty list means the bill is as first received |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or lacks read access to bills |
| 404 | No such bill in your organization, or one your role cannot read |
| 500 | Reading the history failed |

GET `/utility-invoices/{id}/detail`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The bill's record ID

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The bill's rate plan, post and due dates, currency and itemised lines in the utility's order. A bill with no lines answers its dates as null and an empty list |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or lacks org-wide read access |
| 404 | No bill with this id in the organization (another organization's bill answers the same) |
| 500 | Reading the bill's lines failed |

## Emissions and reports (24)

GET `/disclosures`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `limit` | query | No | integer (int64).
\=200.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The organization's saved export snapshots, newest first, without their frozen outputs, factors or inputs |
| 400 | `limit` is not a whole number |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Database error |

POST `/disclosures`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/disclosures`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `export_kind` | string | Yes | 
g. `"csv"`, kept separate from `source` so multiple export formats off the same surface stay distinguishable.

 |
| `factors` | any | No | 

Methodology/citations/conversion factors applied in producing `outputs`, when the surface has any to freeze.

 |
| `inputs` | any | No | 

The raw values `outputs` were derived from, when the surface has something worth freezing beyond `outputs` itself.

 |
| `outputs` | any | Yes | 

The frozen figures as exported, shaped by `source`, opaque here.

 |
| `period_from` | string | Yes | 

Inclusive period start, RFC 3339.

 |
| `period_to` | string | Yes | 

Exclusive period end, RFC 3339.

 |
| `point_in_time` | boolean | No | 

True when the export is a count of now (an alert total, a list as of today) and so covers no span of dates: the period may then be as short as the moment of export. Any other export must cover at least a day.

 |
| `source` | string | Yes | 

g. `"energy-report-csv"`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Disclosure snapshot frozen and persisted (append-only, this call never updates an existing row) |
| 400 | Empty source/export\_kind, invalid period\_from/period\_to, or period\_to not after period\_from |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Database error |

GET `/disclosures/{id}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Disclosure snapshot id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The saved export with its frozen outputs, factors and inputs exactly as stored |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such snapshot in the caller's organization; another organization's id gets the same status and body |
| 500 | Database error |

POST `/downloads`Records that the browser saved a file it built from data it had already read (a report, a series, a table), so the file counts toward the person's day of downloads like a server export does. Any member may record their own download; it changes nothing but the audit log.

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filename` | string | Yes | 
The name the browser saved the file under (only its last segment is kept, at most 200 characters).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 204 | downloaded |
| 400 | No file name was sent |
| 401 | Not signed in |
| 403 | Not a member of the active organization |

GET `/energy/intensity`

Any API token, also Read reports only

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `from` | query | Yes | string.
g. `2025-01-01T00:00:00Z`).

 |
| `to` | query | Yes | string.

Exclusive end, RFC 3339.

 |
| `per` | query | No | string.

`month`: the dates are one Specific month, and the figure is per month, never scaled. Anything else, or absent: per year.

 |
| `building` | query | No | string.

Only this building's row, and a portfolio figure over it alone.

 |
| `carriers` | query | No | string.

Only these fuels, comma separated (`electricity`, `natural-gas`, `steam`, `hot-water`, `chilled-water`, `fuel-oil`, `diesel`, `propane`, `kerosene`): a screen narrowed to one energy type gets that type's Site EUI.

 |
| `series` | query | No | string.

Only the energy read from these series, comma separated ids: a screen narrowed to some meters.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Site EUI and Source EUI per building and for the portfolio, worked out fresh: energy, months with data, area used, the figure scaled to a year (or per month), and month by month energy. |
| 400 | The dates are missing or out of order, or per=month spans more than one calendar month. A period over five years is counted over its last 60 calendar months and says so in annualized\_note |
| 401 | Not authenticated |
| 403 | A person limited to some buildings with no Energy access |
| 500 | A read failed; nothing partial is returned |

GET `/factor-catalog`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every reference factor (energy contents and emission factors, each with the key an organization's own value is filed under) and the fuel by unit by country energy conversions the browser converts readings with |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Error reading the factor catalog |

GET `/factor-overrides`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every value the organization set for a reference factor, retired ones included |
| 401 | Not authenticated |
| 403 | User not registered, or your access is limited to specific buildings |
| 500 | Error reading factor values |

POST `/factor-overrides`

Token that can change data

#### Request body

application/json, required.

A new value.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `effective_from` | string | Yes |  |
| `factor_key` | string | Yes | 
A key from `GET /api/v1/factor-catalog`.

 |
| `justification` | string | Yes | 

Why this value replaces the reference one. Required.

 |
| `scope_iri` | string | No | 

The building, floor or room; absent for the organization.

 |
| `scope_level` | string | Yes | 

"organization", "building", "floor" or "room".

 |
| `value` | number | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 201 | Value saved; reports use it from its start date |
| 400 | Not a catalog factor, a value at or below zero, no reason, or a place of another level |
| 401 | Not authenticated |
| 403 | Only owners and admins can change organization settings |
| 404 | That building, floor or room is not in your organization |
| 409 | That factor already has a value for that place from that date |

PUT `/factor-overrides/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
factor value id

 |

#### Request body

application/json, required.

A changed value for an existing row (same factor, same place).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `effective_from` | string | Yes |  |
| `justification` | string | Yes |  |
| `value` | number | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Changed: the old value is retired and kept on record, the new one names it |
| 400 | A value at or below zero, or no reason |
| 401 | Not authenticated |
| 403 | Only owners and admins can change organization settings |
| 404 | No value in use with this id in your organization |
| 409 | That factor already has another value for that place from that date |

DELETE `/factor-overrides/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
factor value id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 204 | No longer used; kept on record. The published factor applies again |
| 401 | Not authenticated |
| 403 | Only owners and admins can change organization settings |
| 404 | No value in use with this id in your organization |

GET `/insights`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `building` | query | No | string.
Full building IRI, URL-encoded. Without it, the whole portfolio the caller may see.

 |
| `from_month` | query | No | string.

First reading month of the page's banner (`YYYY-MM`, inclusive), as `GET /api/v1/anomalies/summary` takes it. Sets the months the `alerts` part counts; findings stay as of today.

 |
| `to_month` | query | No | string.

Last reading month of the page's banner (`YYYY-MM`, inclusive).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | What BrickFlow noticed for one building (`building`) or the whole portfolio, limited to what the caller may see, most serious first. A source that could not be read is named in `unread`; it is never an empty list. |
| 400 | `building` is not a valid IRI, or `from_month`/`to_month` is not a valid YYYY-MM, or `from_month` is after `to_month` |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 403 | User not registered |

GET `/scope3-entries`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `from` | query | No | string.
Inclusive period start: RFC 3339 or "YYYY-MM-DD" (its UTC date is used).

 |
| `to` | query | No | string.

EXCLUSIVE period end, in the same forms.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The organization's lines overlapping \[from, to), and category totals |
| 400 | from or to missing or not a date, or to not after from |
| 401 | Not authenticated (no session and no valid API token) |
| 403 | This is outside the buildings shared with you. Ask the person who invited you for access. |

POST `/scope3-entries`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activity_amount` | number | No | 
Required for `activity`, zero or more.

 |
| `activity_unit` | string | No | 

).

 |
| `category` | integer | Yes | 

1, 6 or 7.

 |
| `description` | string | No |  |
| `factor_kg_co2e_per_unit` | number | No | 

Required for `activity`: kg CO2e per one unit, zero or more.

 |
| `factor_source` | string | No | 

Required for both methods: the factor's source, or the note for a typed figure.

 |
| `method` | string | No | 

`"activity"` (amount x factor) or `"tonnes"` (typed directly).

 |
| `period_end` | string | No | 

"YYYY-MM-DD", not before `period_start`.

 |
| `period_start` | string | No | 

"YYYY-MM-DD".

 |
| `place_iri` | string | No | 

Where the line sits: a building, space or site of this organization. Absent or null is the whole organization, which only a person who sees the whole organization may enter or change.

 |
| `tonnes_co2e` | number | No | 

Required for `tonnes`, zero or more. Ignored for `activity` (computed).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created |
| 400 | A field is missing, blank, negative, too large or not valid; the body names it |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or you have no write access to this place. Ask the person who invited you for access |

PUT `/scope3-entries/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
scope3\_manual\_entry id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activity_amount` | number | No | 
Required for `activity`, zero or more.

 |
| `activity_unit` | string | No | 

).

 |
| `category` | integer | Yes | 

1, 6 or 7.

 |
| `description` | string | No |  |
| `factor_kg_co2e_per_unit` | number | No | 

Required for `activity`: kg CO2e per one unit, zero or more.

 |
| `factor_source` | string | No | 

Required for both methods: the factor's source, or the note for a typed figure.

 |
| `method` | string | No | 

`"activity"` (amount x factor) or `"tonnes"` (typed directly).

 |
| `period_end` | string | No | 

"YYYY-MM-DD", not before `period_start`.

 |
| `period_start` | string | No | 

"YYYY-MM-DD".

 |
| `place_iri` | string | No | 

Where the line sits: a building, space or site of this organization. Absent or null is the whole organization, which only a person who sees the whole organization may enter or change.

 |
| `tonnes_co2e` | number | No | 

Required for `tonnes`, zero or more. Ignored for `activity` (computed).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Updated; tonnes recomputed from the new values |
| 400 | A field is missing, blank, negative, too large or not valid; the body names it |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or you have no write access to this place. Ask the person who invited you for access |
| 404 | No Scope 3 line with this id in your organization |

DELETE `/scope3-entries/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
scope3\_manual\_entry id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or you have no write access to this place. Ask the person who invited you for access |
| 404 | No Scope 3 line with this id in your organization |

POST `/tabular/detect`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | string | Yes | 
The start of the file's text (the wizard sends at most 64 KiB).

 |
| `filename` | string | No | 

The file's name: a Green Button name keeps the file away from Claude.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | What kind of data the file looks like: every data type ranked by how many columns the alias engine places in it, and a suggestion. A clear names winner answers with no model call; otherwise Claude picks among the data types. When Claude is off, slow, over the organization's daily limit, the organization has its own AI provider, or the file looks like Green Button data (never sent to the AI), the answer is still 200 with claude\_available false and the reason. Nothing is stored |
| 400 | Empty content, an unreadable CSV, or no header row |
| 401 | Not authenticated |
| 403 | User not registered |
| 413 | The content is over 256 KiB (the wizard sends at most the first 64 KiB) |

GET `/tabular/uploads`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | This organization's wizard uploads, newest first, lease files included |
| 401 | Not authenticated (no session and no valid API token) |
| 403 | User not registered, or access limited to specific buildings (a session or a token narrowed to buildings or areas) |

POST `/tabular/uploads`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | No | string.
Optional, 1 to 200 characters. Send the same value when retrying this call (a lost response, a timeout): the first call's answer comes back and nothing is imported twice. Use a new value for each new call. The answer to a repeat carries the header `Idempotent-Replayed: true`. The same value on a different call answers 422.

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | string | Yes | 
The file's text, verbatim (CSV in v1).

 |
| `data_type` | string | Yes |  |
| `filename` | string | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Bytes pinned (a tabular-source ingest job) + the deterministic profile: per-column field proposals (org decisions outrank the engine), date-format candidates, sample rows, and the org's remembered choices for this header shape |
| 400 | Unknown data type, empty content, or an unreadable CSV |
| 401 | Not authenticated |
| 403 | User not registered |
| 429 | The caller has uploaded GK\_UPLOAD\_PER\_MINUTE\_LIMIT files in the last minute; plain text saying when to upload the rest, with Retry-After |

POST `/tabular/uploads/{id}/column-review`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The upload's id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `current` | list of object | Yes |  |
| `current[].band` | string | Yes | 
`decided` | `preselect` | `suggest` | `none`.

 |
| `current[].column` | string | Yes |  |
| `current[].field` | string | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Claude's second opinion on the upload's columns, after the alias engine: a note per undecided column (never a decided one). When Claude is off, slow, over the organization's daily limit, the organization has its own AI provider, or the file looks like Green Button data (never sent to the AI), still 200 with suggestions \[\] and claude\_available false and the reason. Nothing is stored |
| 400 | A current column that is not a header of the file, or an unknown field or band |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such upload in the caller's organization |

POST `/tabular/uploads/{id}/confirm`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The upload's id

 |
| `Idempotency-Key` | header | No | string.

Optional, 1 to 200 characters. Send the same value when retrying this call (a lost response, a timeout): the first call's answer comes back and nothing is imported twice. Use a new value for each new call. The answer to a repeat carries the header `Idempotent-Replayed: true`. The same value on a different call answers 422.

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `corrections` | list of object | No |  |
| `corrections[].column` | string | Yes |  |
| `corrections[].row` | integer | Yes |  |
| `corrections[].value` | string | Yes |  |
| `date_format` | string | No |  |
| `decisions` | list of object | No |  |
| `decisions[].canonical_term` | string | Yes | 
The canonical concept IRI the user confirmed.

 |
| `decisions[].dimension` | string | Yes |  |
| `decisions[].raw_value` | string | Yes |  |
| `mappings` | list of object | Yes |  |
| `mappings[].column` | string | Yes | 

The file's column header, verbatim.

 |
| `mappings[].field` | string | No | 

Target field key, or null = "ignore this column".

 |
| `overwrites` | list of object | No | 

A survey upload's answer to each overwrite it listed: `replace` or `keep`.

 |
| `overwrites[].choice` | string | Yes | 

`replace` | `keep`.

 |
| `overwrites[].key` | string | Yes | 

The overwrite's `key`, as the preview listed it.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Choices recorded as mapping decisions (overrides of an engine preselect flagged for staff review), the mapping remembered for this header shape, and the self-contained tabular-confirmed job run. For a person limited to some buildings, a bill or waste file imports the rows whose meter sits in their buildings and the answer lists the others in `refused_rows`, each with its line and reason |
| 400 | Invalid choices, or vocabulary values left unresolved (never a guess); for a lease upload, any row of the file that fails (all of them are listed) -- nothing is inserted |
| 401 | Not authenticated |
| 403 | User not registered, or a role that cannot modify the organization's data (a lease upload needs an organization-wide writing role); for a person limited to some buildings, a bill or waste file with no row for a meter in their buildings (plain text saying why, nothing imported) |
| 404 | No such upload in this organization |
| 409 | A lease upload that was already imported; confirming it again inserts nothing |

GET `/tabular/uploads/{id}/export`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The upload as CSV in its original layout. Confirmed bills/waste uploads come back REFRESHED from the live time-series (consumption and cost re-read per row, with the fix-it corrections applied); entity and custom uploads come back as confirmed (corrections applied); projects and unconfirmed uploads come back verbatim. |
| 401 | Not authenticated (no session and no valid API token) |
| 403 | User not registered, or access limited to specific buildings (a session or a token narrowed to buildings or areas) |
| 404 | No such upload in this organization |

POST `/tabular/uploads/{id}/preview`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `corrections` | list of object | No |  |
| `corrections[].column` | string | Yes |  |
| `corrections[].row` | integer | Yes |  |
| `corrections[].value` | string | Yes |  |
| `date_format` | string | No |  |
| `mappings` | list of object | Yes |  |
| `mappings[].column` | string | Yes | 
The file's column header, verbatim.

 |
| `mappings[].field` | string | No | 

Target field key, or null = "ignore this column".

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Transformed samples via the SAME engine the confirmed job runs, plus every vocabulary value that would not resolve (each with ranked candidates) |
| 400 | The choices do not compose into a valid document |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such upload in this organization |

GET `/tabular/uploads/{id}/profile`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The upload's id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The profile of an upload that was profiled but not yet confirmed (such as a spreadsheet emailed in), read again from its pinned bytes: the same answer the upload gave |
| 401 | Not authenticated |
| 403 | User not registered, or a role that cannot add data |
| 404 | No such upload in this organization |
| 409 | The upload was already confirmed; its data is in BrickFlow |

POST `/tabular/workbook`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_base64` | string | Yes | 
The workbook's bytes, base64 (standard alphabet).

 |
| `header_row` | integer | No | 

The Excel row (1 is the first) holding the column headers, as the person chose it. Absent: BrickFlow finds it.

 |
| `sheet` | string | No | 

The sheet the person chose. Absent: BrickFlow finds it.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | xls) read for the Add-data wizard: its visible sheets, the sheet and header row BrickFlow chose (names first; Claude only when the names do not settle it, and only when the gate lets the call through, as for detect), and that table as CSV text for the wizard to continue with. A sheet and header row the caller names are used as given. When Claude cannot be used the answer is still 200 with claude\_available false and the reason. Nothing is stored |
| 400 | Not an Excel workbook, no sheet with content, or a sheet or header row that does not exist |
| 401 | Not authenticated |
| 403 | User not registered |
| 413 | The workbook is over 10 MiB, or the chosen sheet is too large to import in one go |

## Alerts (21)

GET `/anomalies`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `month` | query | No | string.
Reporting month (`YYYY-MM`). Absent, the default, returns every alert the org has, which is the current-state inbox view.

 |
| `building` | query | No | string.

A building IRI: only the alerts whose meter sits in that building, the set `building_iri` names. Absent returns every building's (and the alerts in none).

 |
| `from_month` | query | No | string.

First reading month (`YYYY-MM`, inclusive): only the alerts whose `period` is this month or later. Absent leaves the start open. Not together with `month`, which means something else (open during it).

 |
| `to_month` | query | No | string.

Last reading month (`YYYY-MM`, inclusive): only the alerts whose `period` is this month or earlier. Absent leaves the end open.

 |
| `limit` | query | No | integer (int32).

A read without it is deprecated: it answers every alert as a bare array and is kept for automation-key clients only.

 |
| `offset` | query | No | integer (int32).

Alerts to skip before the page, newest first. Only with `limit`; absent is 0.

 |
| `kind` | query | No | string.

Only the alerts of this kind (`missing_period`, `spike`, `drop`, `charge_mismatch`, `missing_bill`, `inactive_meter` or `usage_bill_gap`). Only with `limit`.

 |
| `status` | query | No | string.

Only the alerts in this status (`open`, `acknowledged`, `dismissed` or `healed`). Only with `limit`.

 |
| `meter_key` | query | No | string.

Only the alerts of the consumption series with this `meter_key` (the `meter_key` an alert carries): with `from_month` and `to_month`, one meter's alerts about one month. Only with `limit`.

 |
| `triage` | query | No | string.

tsv`. Only with` limit`.`

 |
| `assigned` | query | No | string.

Only the alerts assigned to the caller (`me`) or to no one (`nobody`). Only with `limit`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | `to_month`, and only `building`'s when given. |
| 400 | `month`, `from_month` or `to_month` given but not a valid YYYY-MM, `from_month` after `to_month`, or `month` together with either; `limit` not between 1 and 200 ("limit must be between 1 and 200"); `offset`, `kind`, `status` or `meter_key` without `limit` ("Use limit with offset, kind, status or meter\_key"); a `kind` that is not an alert kind ("Unknown kind"); a `status` that is not an alert status ("Unknown status"); `triage` or `assigned` without `limit` ("Use limit with triage or assigned"); a `triage` that is not start\_here, later or cleanup; an `assigned` that is not me or nobody |
| 401 | Not authenticated |
| 403 | User not registered |

GET `/anomalies/{id}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | One alert of the caller's organization, exactly as `GET /api/v1/anomalies` returns it, whatever its status or reading month: what a link that names only an alert opens |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such alert in this organization, or a scoped caller's grants do not reach its meter |

POST `/anomalies/{id}/assign`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
id

 |

#### Request body

application/json, required.

`membership_id: None` unassigns.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `membership_id` | integer | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Assignment updated |
| 400 | membership\_id does not belong to this org, or its member cannot see the alert's meter |
| 401 | Not authenticated |
| 403 | User not registered, or lacks write access |
| 404 | No such alert for this org |

POST `/anomalies/{id}/follow-up`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
id

 |

#### Request body

application/json, required.

`on` is the day to look at the alert again (`YYYY-MM-DD`, today or later); `null` clears it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `on` | string | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Follow-up date set, or cleared with `on: null`; the alert is in Follow up later until that day, then in Start here |
| 400 | `on` is not a date (YYYY-MM-DD), is before today, or the alert is closed |
| 401 | Not authenticated |
| 403 | User not registered, or lacks write access |
| 404 | No such alert for this org |

POST `/anomalies/{id}/review`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
id

 |

#### Request body

application/json, required.

`action` is `"acknowledge"` | `"dismiss"` (not a problem) | `"fix"` (the problem was fixed) | `"reopen"`; `note`/ `root_cause` update the stored value only when present (`None` leaves the existing text alone, letting a caller set one without clobbering the other).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | string | Yes |  |
| `note` | string | No |  |
| `root_cause` | string | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Alert status updated; `fix` closes the alert as fixed (who and when are kept), `dismiss` as not a problem |
| 400 | Unknown action, or not a valid transition from the alert's current status |
| 401 | Not authenticated |
| 403 | User not registered, or lacks write access |
| 404 | No such alert for this org |

GET `/anomalies/summary`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `from_month` | query | No | string.
First reading month (`YYYY-MM`, inclusive); absent leaves the start open.

 |
| `to_month` | query | No | string.

Last reading month (`YYYY-MM`, inclusive); absent leaves the end open.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Counts of the caller's alerts by status, open alerts per building and per month, and the newest open alerts; with `from_month`/`to_month`, only those about a reading in that range |
| 400 | `from_month` or `to_month` given but not a valid YYYY-MM, or `from_month` after `to_month` |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/anomaly-mutes`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `muted_kinds` | list of string | No | 
The alert kinds to silence for this meter, any of spike, drop, missing\_period, inactive\_meter, missing\_bill, charge\_mismatch, usage\_bill\_gap. Absent = the first four (what a mute always silenced); an empty list or an unknown kind answers 400.

 |
| `reason` | string | No |  |
| `series_id` | integer | Yes |  |
| `until` | string | No | 

When the mute ends by itself. Absent/omitted = muted until someone removes it; a moment already past answers 400.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Mute created |
| 400 | No kind of alert named, or a kind that cannot be muted |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

DELETE `/anomaly-mutes/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Mute removed |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |
| 404 | No such mute for this org |

GET `/anomaly-settings`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The org's anomaly sensitivity setting and active mutes |
| 401 | Not authenticated |
| 403 | User not registered, or a scoped role |

PUT `/anomaly-settings`

Token that can change data

#### Request body

application/json, required.

One knob at a time -- `None` for any field means "use the compile-time default for that field," meaningful only when `preset == "custom"`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `coldstart_modz_threshold` | number | No |  |
| `min_prior_same_month` | integer | No |  |
| `min_reads_for_cadence` | integer | No |  |
| `min_reads_for_spike` | integer | No |  |
| `modz_threshold` | number | No |  |
| `monthly_gap_max_days` | integer | No |  |
| `monthly_gap_min_days` | integer | No |  |
| `preset` | string | Yes | 
`"high"` | `"medium"` | `"low"` | `"custom"`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Setting saved |
| 400 | Unknown preset |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

POST `/anomaly-settings/preview`

Token that can change data

#### Request body

application/json, required.

One knob at a time -- `None` for any field means "use the compile-time default for that field," meaningful only when `preset == "custom"`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `coldstart_modz_threshold` | number | No |  |
| `min_prior_same_month` | integer | No |  |
| `min_reads_for_cadence` | integer | No |  |
| `min_reads_for_spike` | integer | No |  |
| `modz_threshold` | number | No |  |
| `monthly_gap_max_days` | integer | No |  |
| `monthly_gap_min_days` | integer | No |  |
| `preset` | string | Yes | 
`"high"` | `"medium"` | `"low"` | `"custom"`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Alert counts under the candidate vs. current setting |
| 400 | Unknown preset |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

PUT `/anomaly-settings/usage-bill-gap`

Token that can change data

#### Request body

application/json, required.

1-067).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `threshold_percent` | number | No | 
Percent of the bill, 1 to 100; `null` goes back to the default (10).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Threshold saved; the whole setting as GET returns it |
| 400 | The threshold is outside 1 to 100 percent |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

GET `/calendar`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The static framework-deadline reference list (filtered to the org's buildings' jurisdictions where a clean match exists, otherwise shown in full) merged with the org's own custom events, soonest-first. Lease ends ("lease\_end" rows) follow the Leases read rule, for a session or a token alike |
| 401 | Not authenticated (no session and no valid API token) |
| 403 | User not registered |

POST `/calendar/events`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | No |  |
| `event_date` | string | Yes | 
"YYYY-MM-DD".

 |
| `title` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created |
| 400 | Blank title, or event\_date is not an ISO date |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings |

PUT `/calendar/events/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
calendar\_event id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | No |  |
| `event_date` | string | Yes | 
"YYYY-MM-DD".

 |
| `title` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Updated |
| 400 | Blank title, or event\_date is not an ISO date |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings |
| 404 | No custom event with this id in your organization (a framework-deadline row is never editable) |

DELETE `/calendar/events/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
calendar\_event id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings |
| 404 | No custom event with this id in your organization |

GET `/calendar/preferences`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The caller's own calendar choices in the active organization |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Reading the choice failed |

PUT `/calendar/preferences`

Token that can change data

#### Request body

application/json, required.

`GET`/`PUT /api/v1/calendar/preferences`: what this person's calendar shows.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `show_equipment` | boolean | Yes | 
Equipment warranty ends and service due dates. On unless the person turned it off.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Saved; the caller's own calendar choices |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Saving the choice failed |

GET `/notifications/reminder-setting`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The org's deadline reminder lookahead window, in days |
| 401 | Not authenticated |
| 403 | Scoped roles cannot view this org-wide setting |

PUT `/notifications/reminder-setting`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reminder_window_days` | integer | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Reminder window saved |
| 400 | reminder\_window\_days is not a positive number of days |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |

POST `/notifications/test`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Test email sent |
| 401 | Not authenticated |
| 403 | User not registered |
| 503 | SMTP is not configured on this server |

## Targets (26)

GET `/projects`Lists the organization's projects.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The organization's projects. A member limited to specific buildings sees only the projects whose place their Projects grants reach; a project with no place is org-wide and is not shown to them |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or a member limited to specific buildings holds no Projects grant |
| 500 | Reading the session, resolving the organization, reading the projects or placing a target in the building tree failed |

POST `/projects`Creates the organization's projects, one row and one graph node each; the body is an array (the legacy bulk-insert shape).

Token that can change data

#### Request body

application/json, required. list of object

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | \]}`: the new projects' ids, in request order` |
| 302 | Redirect to `/projects`: the list was empty, so no project was created |
| 400 | Malformed body, 1000 or more projects in one request, a budget, savings figure, start date, actual cost or percent complete out of range, a `lifetime_years` outside 1 to 100, a `budget_year` outside 1900 to 2200, a `cost_currency` that is not three upper-case letters, or a `target_iri` outside this organization or naming nothing a project can target |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or the caller's role cannot modify this organization's data |
| 413 | The body is over the JSON size limit |
| 500 | Reading the session, resolving the organization, checking a target, or writing the projects or their graph nodes failed |

PUT `/projects/{id}`Edits one of the organization's projects.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The project's id

 |

#### Request body

application/json, required.

Body of `PUT /api/v1/projects/{id}`.sql `already comments out).`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actual_cost` | number | No |  |
| `budget` | number | Yes |  |
| `budget_year` | integer | No | 
Calendar year, 1900 to 2200. Absent means null.

 |
| `cost_currency` | string | No | 

Three upper-case letters. Absent or null keeps the stored currency: a project's money never changes currency by omission.

 |
| `description` | string | No |  |
| `lifetime_years` | integer | No | 

Whole years, 1 to 100 (migration 0135). The request is a full replacement: absent means null. Relational only, no graph triple.

 |
| `mandatory` | boolean | No | 

Absent means false.

 |
| `measured_savings` | number | No |  |
| `name` | string | Yes |  |
| `percent_complete` | number | No |  |
| `priority` | string | Yes | One of: high, medium, low, critical. |
| `project_type` | string | Yes |  |
| `projected_savings` | number | No |  |
| `start_date` | integer | No | 

start\_date`'s INTEGER column range at validation (see` types::Project`'s field note).`

 |
| `status` | string | Yes | One of: Proposed, Evaluated, Selected, Initiated, In Progress, On Hold, Completed, Verified, Discarded, Other.

Project lifecycle status: BuildingSync's eight measure-lifecycle values, plus `On Hold` and `Other`.

A status carries nothing of its own, no per-stage dates, owners or fields.status\_other`, not a variant payload.`

 |
| `status_reached_on` | string | No | 

The date the stage in `status` was reached, 'YYYY-MM-DD'. With a status change it dates the new stage (absent means today); with the status unchanged and a date different from the recorded one it corrects the recorded date. Never after today, never before 1900, never before the stage before it. Absent with an unchanged status changes nothing.

 |
| `target_date` | integer | Yes |  |
| `target_iri` | string | No | 

The project's place, in three states. Absent keeps the place; `null` makes the project org-wide; a string moves it to that building, floor or space of the organization (checked like the create request's `target_iri`). A string equal to the stored place is not checked again and changes nothing, so a client may always send the place back.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The project was updated |
| 400 | Malformed body, a budget, savings figure, start date, actual cost or percent complete out of range, a `lifetime_years` outside 1 to 100, a `budget_year` outside 1900 to 2200, a `cost_currency` that is not three upper-case letters, a `target_iri` that is another organization's or names no building, floor or space of this one (nothing is written), a date that cannot be written to the graph, or the graph refused the edit (for example a field set for the first time); the relational row keeps the new values in the last two cases |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or the caller's role cannot modify this organization's data |
| 404 | No project with this id in this organization |
| 413 | The body is over the JSON size limit |
| 500 | Reading the session, resolving the organization, reading or updating the project, or running the graph edit failed |

DELETE `/projects/{id}`Deletes one of the organization's projects.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The project's id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The project and its graph node were deleted; each target it was linked to records the removal in its history |
| 400 | The graph refused to retract the project's node; the project is kept (JSON EditRefusal body) |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered, or the caller's role cannot modify this organization's data |
| 404 | No project with this id in this organization |
| 500 | Reading the session, resolving the organization, reading or deleting the project, or retracting its graph node failed |

POST `/target-programs`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string | Yes | One of: Energy, Water, Waste, Ghg, Data, Certification, Custom. |
| `description` | string | No |  |
| `end_date` | string | No |  |
| `name` | string | Yes |  |
| `offtrack_threshold_pct` | number | No |  |
| `owner_membership_id` | integer | No |  |
| `reminder_lead_days` | number | No | 
5 reach the sentence, not the parser's.

 |
| `scope_iris` | list of string | No | 

Region, campus, site or building IRIs; empty or absent is the whole organization.

 |
| `start_date` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The new program |
| 400 | The body could not be read, or a value breaks a rule; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 500 | Error saving the program |

PUT `/target-programs/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target\_program id

 |

#### Request body

application/json, required.

An absent field is left as it is; `null` clears the five that can be empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string | No | One of: Energy, Water, Waste, Ghg, Data, Certification, Custom. |
| `description` | string | No |  |
| `end_date` | string | No |  |
| `expected_updated_at` | string | No | 
Required: the `updated_at` the caller last read (RFC3339).

 |
| `name` | string | No |  |
| `offtrack_threshold_pct` | number | No |  |
| `owner_membership_id` | integer | No |  |
| `reason` | string | No |  |
| `reminder_lead_days` | number | No |  |
| `scope_iris` | list of string | No |  |
| `start_date` | string | No |  |
| `status` | string | No | One of: Active, Completed, Archived. |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The program as saved |
| 400 | The body could not be read, or a value breaks a rule; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No program with this id in your organization |
| 409 | The program is not active, somebody else saved it first, or it holds targets so its category cannot change |
| 500 | Error saving the program |

DELETE `/target-programs/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target\_program id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Only owners and admins can delete a program, your role cannot modify this organization's data, or User is not registered |
| 404 | No program with this id in your organization |
| 409 | This program has targets or recorded changes, so it cannot be deleted; archive it instead |
| 500 | Error saving the program |

GET `/target-programs/{id}/revisions`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
program id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The program's recorded changes, newest first; they outlive a deleted program |
| 401 | Not authenticated (no session and no valid API token) |
| 402 | subscription\_inactive |
| 403 | User is not registered, your access is limited to specific buildings (ask an owner or admin for access), or the role cannot read a program's history. |
| 404 | No program with this id in your organization |
| 500 | Error reading targets |

GET `/targets`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every program and target of the organization, with live progress for the active ones |
| 401 | Not signed in |
| 402 | subscription\_inactive |
| 403 | User is not registered, or your access is limited to specific buildings (ask an owner or admin for access) |
| 500 | Error reading targets |

POST `/targets`

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `area_unit` | string | No | One of: Ft2, M2. |
| `baseline_start` | string | No |  |
| `baseline_value` | number | No |  |
| `baseline_value_reason` | string | No |  |
| `cert_level` | string | No |  |
| `cert_scheme` | string | No | One of: Leed, BomaBest, EnergyStar, Well, Fitwel, ZeroCarbonBuilding, Other. |
| `cert_scheme_other` | string | No |  |
| `direction` | string | Yes | One of: Reduce, Increase. |
| `form` | string | Yes | One of: Absolute, Intensity, PercentChange, YesNo. |
| `frequency` | string | Yes | One of: Monthly, Quarterly, Annual. |
| `ghg_measure` | string | No | One of: Scope1, Scope2Location, Scope12, Scope3Cat1, Scope3Cat6, Scope3Cat7, Scope3Cat8, Scope3Cat13. |
| `notes` | string | No |  |
| `program_id` | integer | Yes |  |
| `responsible_membership_id` | integer | No |  |
| `start_date` | string | Yes |  |
| `subject_iri` | string | No | 
`null` or absent is the organization; a Portfolio IRI is stored as the organization.

 |
| `survey` | object | No |  |
| `survey.group_id` | integer | Yes |  |
| `survey.question_id` | string | Yes |  |
| `target_date` | string | Yes |  |
| `target_type` | string | Yes | One of: Ghg, SiteEui, EnergyStarScore, Certification, Custom, DataCoverage, DataQuality. |
| `target_value` | number | No |  |
| `title` | string | Yes |  |
| `unit` | string | No | 

A custom target's unit; every other type's is set by the server.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The new target, with its progress |
| 400 | The body could not be read, or a value breaks a rule; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No program with this id in your organization |
| 409 | The program is archived or completed, so it and its targets are read-only |
| 500 | Error saving the target |

GET `/targets/{id}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The target with its progress, chart points, baseline, buildings and provenance |
| 401 | Not signed in |
| 402 | subscription\_inactive |
| 403 | User is not registered, or your access is limited to specific buildings (ask an owner or admin for access) |
| 404 | No target with this id in your organization |
| 500 | Error reading targets |

PUT `/targets/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Request body

application/json, required.

The type, measure, form and subject are accepted only to be refused when they differ.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `area_unit` | string | No | One of: Ft2, M2. |
| `baseline_start` | string | No |  |
| `baseline_value` | number | No |  |
| `baseline_value_reason` | string | No |  |
| `cert_level` | string | No |  |
| `cert_scheme` | string | No | One of: Leed, BomaBest, EnergyStar, Well, Fitwel, ZeroCarbonBuilding, Other. |
| `cert_scheme_other` | string | No |  |
| `direction` | string | No | One of: Reduce, Increase. |
| `expected_updated_at` | string | No | 
Required: the `updated_at` the caller last read (RFC3339).

 |
| `form` | string | No | One of: Absolute, Intensity, PercentChange, YesNo. |
| `frequency` | string | No | One of: Monthly, Quarterly, Annual. |
| `ghg_measure` | string | No | One of: Scope1, Scope2Location, Scope12, Scope3Cat1, Scope3Cat6, Scope3Cat7, Scope3Cat8, Scope3Cat13. |
| `notes` | string | No |  |
| `reason` | string | No | 

Required (1 to 500 characters) when a baseline, a target value, a date, the direction or the area unit changes.

 |
| `responsible_membership_id` | integer | No |  |
| `start_date` | string | No |  |
| `subject_iri` | string | No |  |
| `survey` | object | No |  |
| `survey.group_id` | integer | Yes |  |
| `survey.question_id` | string | Yes |  |
| `target_date` | string | No |  |
| `target_type` | string | No | One of: Ghg, SiteEui, EnergyStarScore, Certification, Custom, DataCoverage, DataQuality. |
| `target_value` | number | No |  |
| `title` | string | No |  |
| `unit` | string | No | 

Accepted only to be refused when it differs: a custom target's unit never changes.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The target as saved, with its progress |
| 400 | The body could not be read, or a value breaks a rule; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization |
| 409 | The program or target is read-only, somebody else saved it first, or the type, measure, form, subject or an ENERGY STAR value or its direction cannot change |
| 500 | Error saving the target |

DELETE `/targets/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Only owners and admins can delete a target, your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization |
| 409 | The program is read-only, or this target has recorded changes so it cannot be deleted; archive it instead |
| 500 | Error saving the target |

POST `/targets/{id}/archive`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The archived target (progress is null, progress\_reason is archived) |
| 400 | The body could not be read, or the reason is over 500 characters |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization |
| 409 | The program is read-only, or this target is already archived |
| 500 | Error saving the target |

PUT `/targets/{id}/gresb`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Request body

application/json, required.

The three answers, all required: a missing one is a 400, so a client cannot clear an answer by leaving it out.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `net_zero` | boolean | Yes | 
The target is a net zero target.

 |
| `publicly_communicated` | boolean | Yes | 

The target has been published outside the organization.

 |
| `science_based` | boolean | Yes | 

5 C science-based pathway, for example validated by SBTi.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The answers as saved (the current ones when nothing changed) |
| 400 | The body could not be read, or one of the three answers is missing |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization |
| 409 | The program is read-only, or the target is archived |
| 500 | Error saving the GRESB answers |

GET `/targets/{id}/initiatives`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The projects linked to the target with their impact in the target's unit, how each counts, and the totals of what counts |
| 401 | Not signed in |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User is not registered, or your access is limited to specific buildings (ask an owner or admin for access) |
| 404 | No target with this id in your organization |
| 500 | Error reading initiatives |

PUT `/targets/{id}/initiatives/{project_id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |
| `project_id` | path | Yes | integer (int32).

project id

 |

#### Request body

application/json, required.

The body of a link: each side null or a number of 0 or more. A side left out is null.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_impact` | number | No |  |
| `measured_impact` | number | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The link as it now stands. A PUT that changes nothing writes no revision and answers the same way |
| 400 | The body could not be read, has an unknown field, or an impact is negative or not a number |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization, or No project with this id in your organization |
| 409 | The program is read-only, or This target is archived, so it is read-only. |
| 500 | Error saving the initiative |

DELETE `/targets/{id}/initiatives/{project_id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |
| `project_id` | path | Yes | integer (int32).

project id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The link is removed and the change recorded |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization, or This project is not linked to this target. |
| 409 | The program is read-only, or This target is archived, so it is read-only. |
| 500 | Error saving the initiative |

GET `/targets/{id}/progress-entries`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The target's typed figures, ascending by period; empty for a target that takes no figures |
| 401 | Not signed in |
| 402 | subscription\_inactive |
| 403 | User is not registered, or your access is limited to specific buildings (ask an owner or admin for access) |
| 404 | No target with this id in your organization |
| 500 | Error reading targets |

POST `/targets/{id}/progress-entries`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string | No |  |
| `period_start` | string | Yes | 
The first day of the month, quarter or year the figure covers.

 |
| `value` | number | Yes | 

At or above 0; 1 or 0 for a yes or no target.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The target's figures and the target with its progress; the target's updated\_at is unchanged |
| 400 | The body could not be read, or the period, value or note breaks a rule; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization |
| 409 | The program or target is read-only, the target's progress is not typed, or there is already a figure for this period |
| 500 | Error saving the figure |

PUT `/targets/{id}/progress-entries/{entry_id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |
| `entry_id` | path | Yes | integer (int64).

figure id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_updated_at` | string | No | 
Required: the figure's `updated_at` as last read (RFC3339).

 |
| `note` | string | No | 

Absent leaves the note alone; null or blank clears it.

 |
| `reason` | string | No | 

Required (1 to 500 characters).

 |
| `value` | number | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The target's figures and the target with its progress; a correction that changes nothing records nothing |
| 400 | The body could not be read, the reason or expected\_updated\_at is missing, or the value or note breaks a rule; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization, or No progress figure with this id on this target |
| 409 | The program or target is read-only, the target's progress is not typed, or somebody else changed this figure first |
| 500 | Error saving the figure |

DELETE `/targets/{id}/progress-entries/{entry_id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |
| `entry_id` | path | Yes | integer (int64).

figure id

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_updated_at` | string | No | 
Required: the figure's `updated_at` as last read (RFC3339).

 |
| `reason` | string | No | 

Required (1 to 500 characters).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The target's remaining figures and the target with its progress; the deletion and its reason stay in history |
| 400 | The body could not be read, or the reason or expected\_updated\_at is missing; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No target with this id in your organization, or No progress figure with this id on this target |
| 409 | The program or target is read-only, the target's progress is not typed, or somebody else changed this figure first |
| 500 | Error saving the figure |

GET `/targets/{id}/revisions`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
target id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The target's recorded changes, newest first; they outlive a deleted target |
| 401 | Not authenticated (no session and no valid API token) |
| 402 | subscription\_inactive |
| 403 | User is not registered, your access is limited to specific buildings (ask an owner or admin for access), or the role cannot read a target's history. |
| 404 | No target with this id in your organization |
| 500 | Error reading targets |

POST `/targets/from-energy-star`

Token that can change data

#### Request body

application/json, required.

It has no value, type, form, direction, origin, unit, subject or typed baseline: the server reads ENERGY STAR's target from the graph and sets those, so a body cannot pass its own number off as ENERGY STAR's. Serde drops any such field a client sends.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `baseline_start` | string | No |  |
| `building_iri` | string | Yes |  |
| `frequency` | string | Yes | One of: Monthly, Quarterly, Annual. |
| `notes` | string | No |  |
| `program_id` | integer | Yes |  |
| `responsible_membership_id` | integer | No |  |
| `start_date` | string | Yes |  |
| `target_date` | string | Yes |  |
| `title` | string | No |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The new target, copied from the building's ENERGY STAR target, with its progress |
| 400 | The body could not be read, a value breaks a rule, the building has no ENERGY STAR target, or there is no data for the baseline period; the body is the sentence |
| 401 | Not signed in, or only an API token (tokens never write) |
| 402 | subscription\_inactive |
| 403 | Your role cannot modify this organization's data, or User is not registered |
| 404 | No program with this id in your organization |
| 409 | The program is archived or completed, so it and its targets are read-only, or ENERGY STAR has two values for this building's target |
| 422 | ENERGY STAR's target is a percent better than the national median, or the baseline period must be confirmed |
| 500 | Error saving the target |

GET `/targets/gresb`

Any API token, also Read reports only

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The GRESB answers of every target that has any; a target missing here has all three answers no |
| 401 | Not signed in |
| 402 | subscription\_inactive |
| 403 | User is not registered, or your access is limited to specific buildings (ask an owner or admin for access) |
| 500 | Error reading the GRESB answers |

GET `/targets/summary`

Any API token, also Read reports only

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | How many active targets are on track, off track, incomplete or achieved |
| 401 | Not signed in |
| 402 | subscription\_inactive |
| 403 | User is not registered, or your access is limited to specific buildings (ask an owner or admin for access) |
| 500 | Error reading targets |

## ENERGY STAR Portfolio Manager (6)

GET `/espm-project-reviews`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The choices an ENERGY STAR re-import waits for, oldest first |
| 401 | Not authenticated |
| 403 | The caller's access is limited to specific buildings |
| 500 | The choices could not be read |

POST `/espm-project-reviews/{id}/resolve`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The review's number

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `choice` | string | Yes | 
`link`, `keep_both`, `keep_mine` or `take_theirs`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The choice was applied; the review is kept as a record |
| 400 | The choice is not one of those offered for this review |
| 401 | Not authenticated |
| 403 | The caller's role cannot change this organization's data |
| 404 | No open choice with that number in this organization |
| 409 | Another project here already holds that ENERGY STAR project |
| 500 | The choice could not be saved, or the project's graph copy did not update |

GET `/espm-projects`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | ENERGY STAR-tracked improvement projects, org-wide |
| 401 | Not authenticated |
| 403 | Caller holds no Domain::Projects grant at all |
| 500 | The projects could not be read from the graph store |

GET `/espm-sync/org-enrollments`\`GET /api/v1/espm-sync/org-enrollments\`: every ENERGY STAR Portfolio Manager scheduled-sync enrollment in the caller's ACTIVE org, today only the enrolled user themselves can see their own row; an org owner has zero visibility into a background writer syncing into their own graph unless the enrolled member happens to mention it.

Token that only reads

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every ENERGY STAR Portfolio Manager scheduled-sync enrollment in the caller's org |
| 401 | Not authenticated |
| 403 | Only owners and admins can view org-wide enrollments |

GET `/espm/property-buildings`property\_id)\` call site). This endpoint is that SAME function, not a new lookup, no database or graph read at all.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `property_ids` | query | Yes | string.
Comma-separated ENERGY STAR Portfolio Manager property ids, up to \[`PROPERTY_IDS_MAX`\].

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The BrickFlow building IRI each named property maps to, same order as the request |
| 400 | property\_ids empty, non-numeric, or names more than the per-request limit |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/espm/sync`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | ENERGY STAR Portfolio Manager sync submitted per connected account and run as ingest jobs. Each ok run carries `periods_already_filled` (up to 50) and `readings_set_aside` (all), the bill periods it found already filled with a different value, for an organization-wide role |
| 400 | No connected ENERGY STAR Portfolio Manager account for this organization |
| 401 | Not authenticated |
| 403 | User not registered |
| 503 | ENERGY STAR Portfolio Manager is not configured on this server |

## Green Button (6)

GET `/green-button/notification`A utility portal checks the notify address with a plain GET before it sends a notification. Answering 200 (empty, no DB, no state) lets that URL check pass; it reveals nothing, and the POST above stays the only way in.

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The notify address is reachable. Empty body. |

POST `/green-button/notification`

Token that can change data

#### Request body

application/atom+xml, required. string

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Notification accepted; resolvable resource URIs are fetched asynchronously. Unresolvable URIs (unregistered origin, unknown subscription, provider not opted into push) are logged and skipped, deliberately not distinguishable to the sender. |
| 400 | Body is not a well-formed BatchList |
| 404 | None of the listed resources belongs to a subscription BrickFlow holds for a utility set up for notices (or the sender is not accepted). One fixed body for every reason, so it reveals nothing about what BrickFlow holds. |
| 429 | Rate limit exceeded |

GET `/green-button/providers`\`GET /api/v1/green-button/providers\`: registry listing.sql\`, let alone echoed here.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Registered utility providers (public fields only) |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Database error |

GET `/green-button/sync-runs/{id}`\`GET /api/v1/green-button/sync-runs/{id}\`: where a sync the person started stands.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | string.
sync\_id from POST /api/v1/green-button/sync/{slug}

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | `running`, or `done` with the status and body the sync ended with |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such run for this person: unknown, older than 15 minutes, or lost by a restart |

POST `/green-button/sync/{slug}`\`POST /api/v1/green-button/sync/{slug}\`: session/org resolution, the \`GK\_CRED\_KEY\` prologue and the checks that belong to the request (utility known, account stored: 404 otherwise), then 202 with a \`sync\_id\` while a task runs \[\`sync\_org\_provider\_account\`\].6 s on the live site (ENG-460), so the request no longer waits for it: the caller reads \`GET /api/v1/green-button/sync-runs/{id}\` for the status and body the sync used to answer (\[\`sync\_outcome\_parts\`\]: any "ok" 200, all waiting 202, all "expired" 409, other failures 500).

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `slug` | path | Yes | string.
slug

 |
| `subscription_id` | query | No | string.

Sync only this account (ESPI subscription id) instead of every account of the utility

 |
| `wait` | query | No | boolean.

true: answer when the sync has finished with its status and body (200, 202, 409, 500), as before ENG-460. Requests carrying an automation key (Authorization header) get this answer without asking, for one release; the next release answers 202 to them too

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 202 | The sync started (or the one already running for this account was joined). Read `GET /api/v1/green-button/sync-runs/{sync_id}` until `state` is `done`; its `http_status` and `body` (a GreenButtonSyncResponse) are what this request answered before ENG-460: 200 at least one authorization synced, 202 every account is waiting for the utility's notice, 409 every authorization expired, 500 every authorization failed |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | Unknown provider, or no stored authorization for this org/provider |
| 500 | Missing GK\_CRED\_KEY or a database error while checking the request |

POST `/green-button/upload`

Token that can change data

#### Request body

application/atom+xml, required. string

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | DMD upload submitted and run as an ingest job (job may be committed or failed). `periods_already_filled` (up to 50) and `readings_set_aside` (all) name the bill periods it found already filled with a different value |
| 401 | Not authenticated |
| 403 | User not registered |
| 413 | Payload too large |
| 429 | The caller has uploaded GK\_UPLOAD\_PER\_MINUTE\_LIMIT files in the last minute; plain text saying when to upload the rest, with Retry-After |
| 500 | Ingest error |

## Connected sources (26)

GET `/connector-requests`This org's connector roadmap -- seeded planned-but-unbuilt connectors plus any free-text suggestions, most-upvoted first.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Roadmap items, most-upvoted first |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/connector-requests`Suggest a connector not already on the roadmap. A name matching an existing item (case/whitespace-insensitively -- a seed placeholder or an earlier suggestion) merges onto that item instead of forking a duplicate vote target.

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/connector-requests`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | No |  |
| `name` | string | Yes |  |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Suggestion recorded (or merged onto an existing same-name item) |
| 400 | Empty name |
| 401 | Not authenticated |
| 403 | User not registered |
| 500 | Database error |

PUT `/connector-requests/{id}/upvote`Cast the caller's upvote. Idempotent -- casting twice is a no-op, never an error (the \`connector\_request\_upvote\` primary key is what actually prevents a duplicate vote; see \`sql\_db\_api::connector\_request::upvote\`).

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Upvote recorded (idempotent) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such connector request in this org |
| 500 | Database error |

DELETE `/connector-requests/{id}/upvote`Retract the caller's upvote. Idempotent -- retracting a vote that was never cast is a no-op, never an error.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Upvote retracted (idempotent) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such connector request in this org |
| 500 | Database error |

GET `/external-grants`\`GET /api/v1/external-grants\`, "Shared with you" (plan §16).

Any API token

org\_id`, and re-reading them here would be a second definition of the same thing that could drift from the one every authorization check uses.`

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Entities other organizations have shared with this one |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings |

GET `/external-grants/{id}/bills`\`GET /api/v1/external-grants/{id}/bills\`, the bills of the shared building's meters. Needs Financial, and Energy too (a bill carries consumption), each with its meters.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |
| `from` | query | No | integer (int64).

Inclusive lower bound on `end_date`.

 |
| `to` | query | No | integer (int64).

Exclusive upper bound on `start_date`.

 |
| `limit` | query | No | integer (int64).

Bills per page: 200 when absent, at most 500 (a larger value is read as 500), at least 1.

 |
| `offset` | query | No | integer (int64).

Bills to skip, newest first: 0 when absent, never negative.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | One page of the bills of the meters in the shared building, newest first, from the granting org (the trailing 24 months unless `from` is given); `has_more` says whether a further page exists; empty when the grant excludes meters |
| 400 | `limit` is below 1 ("limit must be 1 or more") or `offset` is negative ("offset must be 0 or more") |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, this grant does not cover financial, or the building's bills were shared without energy |
| 404 | No such grant shared with this organization |
| 500 | The shared scope, the bills or the currency could not be read |

GET `/external-grants/{id}/building-summary`\`GET /api/v1/external-grants/{id}/building-summary\`, plan §16's read path, and the whole of it.

Any API token

Deliberately NOT a general cross-org read. Every input that could name an entity comes from the grant row, not the request:

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The shared building's summary, read from the granting org's graph |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover topology |
| 404 | No such grant shared with this organization |
| 500 | The graph store did not answer a count or the owners read |

GET `/external-grants/{id}/data-sources`\`GET /api/v1/external-grants/{id}/data-sources\`, which connectors fed the shared building. The connector lineage of the granting organization's graph (one select), kept to the buildings the scope covers; a connector left with none is dropped. No ingest jobs, documents or uploader names: those name the managing organization's people.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The connectors that fed the shared building, from the granting org's graph |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover data sources |
| 404 | No such grant shared with this organization |
| 500 | The shared scope or the connector lineage could not be read |

GET `/external-grants/{id}/energy`\`GET /api/v1/external-grants/{id}/energy\`, the shared building's twelve calendar months of energy in one small read. It counts exactly the series \`owner\_series\_get\` lets through (the building's meters kept by \`covers\`, none when the grant withholds meters), converts each through the unit catalog the EUI module uses, and sums them by UTC month in Postgres.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Twelve UTC months of the shared building's energy in kWh equivalent, from the covered meters; null months and `meters_included = false` when there is nothing to count |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover energy |
| 404 | No such grant shared with this organization |
| 500 | The shared scope, the readings, the unit catalog, the building's jurisdiction or its costs could not be read |

GET `/external-grants/{id}/equipment`\`GET /api/v1/external-grants/{id}/equipment\`, the equipment inside the shared entity.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The shared entity's equipment, from the granting org's graph |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover equipment |
| 404 | No such grant shared with this organization |
| 500 | The shared scope or the building's equipment could not be read |

GET `/external-grants/{id}/leases`\`GET /api/v1/external-grants/{id}/leases\`, the granting organization's leases whose target (a space, else a building) is the shared entity or inside it.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Leases inside the shared building, from the granting org; no tenant organization id, link flag or linked organization name |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover leases |
| 404 | No such grant shared with this organization |
| 500 | The shared scope or the leases could not be read |

GET `/external-grants/{id}/meters`\`GET /api/v1/external-grants/{id}/meters\`, the shared entity's meters.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The shared entity's meters, from the granting org's graph; empty when the grant excludes meters |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover energy |
| 404 | No such grant shared with this organization |
| 500 | The shared scope or the building's meters could not be read |

GET `/external-grants/{id}/projects`\`GET /api/v1/external-grants/{id}/projects\`, the granting organization's projects aimed inside the shared building, and its ENERGY STAR Portfolio Manager improvement projects.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Projects targeted inside the shared building, from the granting org |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover projects |
| 404 | No such grant shared with this organization |
| 500 | The shared scope or the projects could not be read |

GET `/external-grants/{id}/series`\`GET /api/v1/external-grants/{id}/series\`, the readings of the shared building's meters. Cost, provider and account number come back only when the owner also holds Financial on the same building, with its meters.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |
| `series_ids` | query | No | string.

id `values, as the building's meters list them (`series\_id`), up to 200.`

 |
| `start` | query | No | string (date-time).

Inclusive lower bound, RFC 3339.

 |
| `end` | query | No | string (date-time).

Exclusive upper bound, RFC 3339.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Readings of the requested meters that sit in the shared building, from the granting org; ids outside it are absent |
| 400 | series\_ids is missing, malformed, empty or names more than 200 ids |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover energy |
| 404 | No such grant shared with this organization |
| 500 | The shared scope, the building's meters, the readings or the currency could not be read |

GET `/external-grants/{id}/spaces`\`GET /api/v1/external-grants/{id}/spaces\`, the shared entity and its space hierarchy, read from the granting organization's graph.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The shared entity with its space tree, from the granting org's graph |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover topology |
| 404 | No such grant shared with this organization |
| 500 | The shared scope or its spaces could not be read |

GET `/external-grants/{id}/sustainability`\`GET /api/v1/external-grants/{id}/sustainability\`, the shared building's reported metrics, ENERGY STAR Portfolio Manager target and certifications, all read against the granting organization.

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The org\_grant id from GET /api/v1/external-grants

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The shared building's sustainability facts, from the granting org |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings, or this grant does not cover sustainability |
| 404 | No such grant shared with this organization |
| 500 | The shared scope, the reported metrics, the target or the certifications could not be read |

GET `/ingest/connectors`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Registered connector descriptors |
| 401 | Not authenticated |

GET `/ingest/connectors/buildings`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Buildings each connector's provenance has touched, grouped by connector id.rq) -- not an authoritative connector-to-building model, since connectors are org-level integrations with no building association of their own. Manual entries carry no gk:connectorId and never appear.g. a connector that has only appended readings to buildings someone else minted) is simply absent from the list, not present with an empty array. |
| 401 | Not authenticated |
| 403 | User not registered |

GET `/ingest/jobs`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `recent` | query | No | integer (int32).
Answer a digest instead of the whole history: the `recent` newest jobs (at most 200), plus each source's newest job, its newest job still in progress and its newest committed job that brought rows. Newest first, each job once. For summary screens (Home, the first data step).

 |
| `connector` | query | No | string.

Only this source's jobs (a connector id such as `green-button`), for a source's own history screen. With `recent`, the digest is picked from this source's jobs.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Ingest jobs, newest first.g. a scheduled sync of their own anchored connection). No element carries `periods_already_filled` or `readings_set_aside`: open one job for them |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/ingest/jobs`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | No | string.
Optional, 1 to 200 characters. Send the same value when retrying an upload (a lost response, a timeout): the first call's job comes back and nothing is imported twice. Use a new value for each new upload. The answer to a repeat carries the header `Idempotent-Replayed: true`.

 |

#### Request body

application/json, required.

Body of `POST /api/v1/ingest/jobs`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `anchor_iri` | string | No | 
The building, space or site this upload is for. A person limited to some buildings must give it, and needs a write grant covering it; the job is then listed with that place's own jobs.

 |
| `connector_id` | string | Yes | 

Registered connector id (see `GET /api/v1/ingest/connectors`).

 |
| `encoding` | string | No | One of: text, base64.

How `payload` is encoded in a job submission.

 |
| `filename` | string | No |  |
| `payload` | string | Yes | 

The payload, as text or base64 per `encoding`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Job ran to completion (status committed or failed). `periods_already_filled` (up to 50) and `readings_set_aside` (all) name the bill periods it found already filled with a different value |
| 400 | Unknown connector or undecodable payload |
| 401 | Not authenticated |
| 403 | User not registered, or limited to some buildings: a file import is refused to them |
| 409 | A workbook for an organization whose buildings wait for the one-time building rename, which has not run yet; or the same `Idempotency-Key` is still being imported by an earlier call (nothing was written; try again in a minute) |
| 422 | The `Idempotency-Key` was already used for a different upload; nothing was written |

GET `/ingest/jobs/{id}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Ingest job id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Job detail incl. raw\_ref and provenance IRI; for an organization-wide role also `periods_already_filled` (up to 50) and `readings_set_aside` (all) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such job in this org, including, for a scoped (tenant/contractor) role, any job they didn't personally initiate and that isn't anchored in their granted scope (indistinguishable by design) |

POST `/ingest/jobs/{id}/retry`6-005: re-drive a \`failed\` job from its already-pinned raw payload, \`Pipeline::run\` re-fetches by \`raw\_ref\` and re-executes stage → map → validate → commit, so this needs no re-upload and no connector-specific re-trigger. Refuses anything but \`failed\`: a job still in flight (acquired/staged/mapped/validated) may be mid-request elsewhere, and an already-\`committed\` job has nothing to retry.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Ingest job id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Job re-run to completion (status committed or failed again), with `periods_already_filled` (up to 50) and `readings_set_aside` (all) |
| 400 | The job is not in a retryable (failed) state |
| 401 | Not authenticated |
| 403 | User not registered, or lacks write access |
| 404 | No such job in this org |
| 409 | A workbook job of an organization whose buildings wait for the one-time building rename, which has not run yet; the job stays failed |

POST `/ingest/jobs/{job_id}/reading-conflicts/resolve`One choice settles every bill period an upload found already filled (QB-2: a Green Button restatement can set aside thousands of intervals).

Token that can change data

The periods are exactly those the upload's own result lists (`periods_already_filled`): the open row at each period the upload set aside that proposes the upload's value, its own or, for a value it re-sent, the earlier upload's. Someone with edit rights (owner, admin, editor) chooses, under the pipeline's org commit lock. ONE transaction: the rows are locked, the saved bills behind them read once, and each row settled exactly as the per-period choice settles it (\[`settle_in_tx`\]); a row whose saved or new value changed, or whose period another reading holds, stays open and is counted in `left_open`, never failing the call. After it commits and the lock is released, a `replace` lands the upload's bills for every period someone replaced with its value (this call's and any earlier replace whose landing failed): one payload parse per upload, never per period.

Cost: one locking statement, one bill read, then two to six statements per decided row in one transaction under the org lock (thousands of interval rows is one click, seconds of work during which that organization's imports wait; human-driven and rare), then one statement and one payload parse to land bills.

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `job_id` | path | Yes | integer (int64).
The upload's ingest job id

 |

#### Request body

application/json, required.

Body of `POST /api/v1/ingest/jobs/{job_id}/reading-conflicts/resolve`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `choice` | string | Yes | 
`replace` makes every value the upload is waiting on the saved reading; `keep` keeps every saved one.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Settled: `decided` periods are `took_proposed` or `kept_recorded`, `left_open` stay open (each can be chosen on its own) |
| 400 | An unknown choice ("choice must be \\"replace\\" or \\"keep\\""); nothing changed |
| 401 | Not authenticated |
| 402 | The organization's subscription has ended (`subscription_inactive`) |
| 403 | User not registered; a role that cannot edit; or a role limited to specific buildings with no write access to any meter this upload is waiting on |
| 404 | No such upload in this organization |
| 409 | The upload did not finish, so its values cannot be chosen; or a replace would land workbook bills before the building rename has finished; nothing changed |
| 500 | Saving the choice failed and nothing changed; or the new values are saved but their bills could not be added (the body says so; choosing replace again adds them) |

GET `/setup-emails/unsubscribe`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `token` | query | No | string.
The token from the email's link.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | A page asking to confirm stopping setup emails (HTML; no sign-in needed) |
| 400 | The token is missing, cut short or not BrickFlow's (HTML page saying so) |
| 503 | The server cannot check tokens yet (HTML page saying so) |

POST `/setup-emails/unsubscribe`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `token` | query | No | string.
The token from the email's link.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Setup emails stopped for this person and organization (HTML page saying so; also the RFC 8058 one-click target) |
| 400 | The token is missing, cut short or not BrickFlow's (HTML page saying so) |
| 500 | The choice could not be saved (HTML page saying so) |
| 503 | The server cannot check tokens yet (HTML page saying so) |

POST `/webhooks/resend-inbound`

Token that can change data

#### Request body

application/json, required. string

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Verified and recorded: the email was accepted (its files are imported in the background), held for approval, already received, or for no organization's address |
| 400 | Body too large, or signed but not an event BrickFlow can read |
| 401 | Unsigned, a signature that does not match, or signed more than five minutes from now |
| 409 | This delivery was already received (a replay); nothing was done |
| 500 | Verified but recording failed; the mail service may send it again |
| 503 | Emailing bills in is not switched on or not fully set up on this server |

## Documents (10)

GET `/documents`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `limit` | query | No | integer (int64).
The newest this many documents the caller can see, 1 to 2000. Opt-in: without it every one comes back, as before.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Uploaded documents visible to the caller, newest first (each with the latest attempt's duration\_ms and token counts, all three null for contractor and tenant): every org document for an org-wide role, or (scoped roles) only their own uploads plus others anchored inside their granted subtree, or with `limit` only the newest that many of them |
| 400 | `limit` is not a whole number or not between 1 and 2000 ("limit must be between 1 and 2000") |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/documents`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | No | string.
Optional, 1 to 200 characters. Send the same value when retrying this call (a lost response, a timeout): the first call's answer comes back and nothing is staged twice. Use a new value for each new file. The answer to a repeat carries the header `Idempotent-Replayed: true`. The same value on a different file answers 422.

 |

#### Request body

application/json, required.

Body of `POST /api/v1/documents`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `anchor_iri` | string | No | 
The granted building/space this upload attaches to.

 |
| `document_type` | string | Yes |  |
| `filename` | string | No | 

Original filename, recorded as the ingest job's `source_detail`.

 |
| `payload` | string | Yes | 

Base64-encoded file bytes.

 |
| `upload_batch_id` | string | No | 

randomUUID()`) and sends on every file of the same multi-file session, so` GET /api/v1/documents/batches `can later recover "3 uploaded, 2 extracted, 1 failed" as a reviewable card.`

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Uploaded and staged for extraction (status=pending) |
| 400 | Unregistered document\_type, undecodable base64, an unsupported file type (not a PDF/PNG/JPEG), or (scoped roles only) a missing anchor\_iri |
| 401 | Not authenticated |
| 403 | User not registered, or (scoped roles only) anchor\_iri is outside the caller's granted write scope |
| 429 | The caller has uploaded GK\_UPLOAD\_PER\_MINUTE\_LIMIT files in the last minute, or (bills read by BrickFlow's shared engine, not by the organization's own) the organization has used today's GK\_EXTRACT\_DAILY\_LIMIT bill readings; plain text saying when it reopens, with Retry-After |
| 500 | Ingest or database error |

GET `/documents/{id}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Document extraction id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Extraction detail incl. per-field confidence, and what the latest attempt cost: started\_at/finished\_at/duration\_ms, attempt\_count, input/output tokens and the engine+prompt that produced it. For contractor and tenant the engine, prompt, token and timing fields are null and a failure's error is one fixed sentence; attempt\_count and needs\_manual\_entry are unchanged |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such document in this org, or (scoped roles only) not visible to the caller, same status as not-found, never a different code that would leak existence |

POST `/documents/{id}/confirm`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Document extraction id

 |

#### Request body

application/json, required.

Body of `POST /api/v1/documents/{id}/confirm`. Corrections not resent here but saved by a prior (failed) confirm attempt still apply -- `corrected_value` is durable per-field state, not per-request.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `allow_duplicate` | boolean | No | 
Keep both: confirm even though a bill for the same meter and period is already saved with DIFFERENT numbers. A bill identical to a saved one is refused all the same (backlog i084-34).

 |
| `allow_future_dated` | boolean | No | 

Keep a bill whose billing period ends after today. Without it such a bill is refused with 409 `future_dated_bill` and the document stays `extracted` and reviewable.

 |
| `buildings` | list of object | No | 

The existing building picked per record. A record with no entry here is attached by exact match of its service address, as before.

 |
| `buildings[].building_iri` | string | Yes | 

A building in this organization's graph.

 |
| `buildings[].record_idx` | integer | Yes | 

One of the records being confirmed.

 |
| `corrections` | list of object | No |  |
| `corrections[].field_key` | string | Yes |  |
| `corrections[].record_idx` | integer | Yes | 

Usually an EXISTING record from the extraction.

 |
| `corrections[].value` | string | Yes | 

The corrected value.

 |
| `manual_entry` | boolean | No | 

finish THIS upload by hand, in place, because no extraction engine is configured (`pending`) or extraction failed (`failed`).

 |
| `replace` | boolean | No | 

With `allow_duplicate`: this bill REPLACES the saved one, which the caller deletes right after, rather than being kept beside it. Its reading is never added to the bill it replaces.

 |
| `utc_offset_minutes` | integer | No | 

The browser's minutes east of UTC, so "after today" means the person's own day (an uploaded bill's dates are UTC midnights). 0 when absent.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Confirmed: a new deterministic ingest job committed the invoice(s). `periods_already_filled` (up to 50) and `readings_set_aside` (all) name the bill periods it found already filled with a different value |
| 400 | A correction named a field not on this extraction (or not on its document type, for a manual\_entry confirmation), a field value is not a valid number, a manual\_entry confirmation is missing a required field, or a building choice names no record being confirmed, names one record twice, names a building not in this organization, or gives two records on one meter different buildings |
| 401 | Not authenticated |
| 403 | User not registered, or a scoped role (contractor/tenant), unchanged for manual\_entry confirmations |
| 404 | No such document in this org |
| 409 | A bill ends after today (`future_dated_bill`; send `allow_future_dated: true` to keep it; `row` is the first such bill and `rows` names every one; `utc_offset_minutes` sets the day that counts as today). Or: Document is not in status=extracted (send manual\_entry=true to finish a pending/failed document by hand instead), a chosen building would give a meter that already sits in another building a second one, or a bill is already saved for the same meter and billing period (`duplicate_bill`; the document stays reviewable). `identical: true`: the same numbers, refused even with `allow_duplicate`. `identical: false`: different numbers; resend with `allow_duplicate: true` to keep both. The body names the saved bill (`existing_id`, `existing`), every saved copy (`existing_ids`), the record (`row`, with its `record_idx`), every hit (`duplicates`) and a `message`. Two identical bills in the document itself are refused the same way as `identical: true`, naming the earlier copy in `duplicate_of` (with its `record_idx`; then `existing_id` is 0 and `existing_ids` empty) |
| 500 | Ingest or database error |

GET `/documents/{id}/file`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Document extraction id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The original uploaded bytes, with the sniffed content type and an inline Content-Disposition naming the uploaded file (cleaned) |
| 401 | Not authenticated |
| 403 | User not registered |
| 404 | No such document in this org, or (scoped roles only) not visible to the caller, same status as not-found, never a different code that would leak existence |

POST `/documents/{id}/retry`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
Document extraction id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | A new extraction attempt was started |
| 401 | Not authenticated |
| 403 | User lacks write access, or is a scoped role |
| 404 | No such document in this org |
| 409 | Document is not in a retryable (pending/failed) state, or it failed in a way retrying cannot fix (the engine declined it, or cut its answer off) and needs manual entry |
| 429 | The organization (reading with BrickFlow's shared engine) has used today's GK\_EXTRACT\_DAILY\_LIMIT bill readings; plain text saying when reading reopens, with Retry-After. The document is left as it was |
| 500 | Database error |
| 503 | No extraction engine can read this organization's bills: none is configured, or its own provider's saved key can't be used, and the uploader has no AI key of their own (a bill on its uploader's own key is retried without one and takes no daily reading) |

GET `/documents/accuracy-stats`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | 1's >=95% extraction-accuracy target |
| 401 | Not authenticated |
| 403 | User not registered, or a scoped role (contractor/tenant), this is an org-wide aggregate, not filtered per grant |

GET `/documents/batches`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Recent multi-file upload batches with per-status counts |
| 401 | Not authenticated |
| 403 | User not registered |

POST `/documents/retry-failed`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/documents/retry-failed`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `upload_batch_id` | string | Yes | 
The batch, as `GET /api/v1/documents/batches` names it.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every failed document in the batch that a retry can fix was queued again (possibly none); the ones retrying cannot fix are left as they are and counted in not\_retryable |
| 400 | upload\_batch\_id is not 1-64 characters |
| 401 | Not authenticated |
| 403 | User lacks write access, or is a scoped role |
| 404 | No upload batch with this id in this org |
| 429 | Reading every retryable failed bill in the batch again would pass the organization's GK\_EXTRACT\_DAILY\_LIMIT bill readings for today; no bill is queued, plain text saying when reading reopens, with Retry-After |
| 500 | Database error |
| 503 | No extraction engine can read this organization's bills: none is configured, or its own provider's saved key can't be used, and no retryable failed bill's uploader has an AI key of their own (those bills are retried on that key, take no daily reading, and are the only ones queued when no engine is configured) |

GET `/documents/upload-anchors`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The caller's own DataSources-write grants, labeled, empty for org-wide roles, whose uploads never anchor |
| 401 | Not authenticated |
| 403 | User not registered |

## Leases (4)

GET `/leases`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `building` | query | No | string.
Only this building's leases (full IRI, URL-encoded).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every lease the caller may read, optionally of one building. A scoped member sees a lease only when a Leases grant covers its space (else its building) |
| 401 | Not authenticated (no session and no valid API token) |
| 403 | building= the answer is an empty list) |
| 500 | Error reading the leases or the graph |

POST `/leases`

Token that can change data

#### Request body

application/json, required.

Body of `POST /api/v1/leases` and `PUT /api/v1/leases/{id}`: the whole lease, every time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `building_iri` | string | Yes | 
A building of this organization (full IRI).

 |
| `end_date` | string | No | 

`YYYY-MM-DD`, on or after `start_date`; omit or `null` for open-ended.

 |
| `lease_type` | string | Yes | 

One of `gross`, `net`, `modified_gross`, `triple_net`, `other`.

 |
| `space_iri` | string | No | 

A floor, room or space inside `building_iri`; omit or `null` for the whole building.

 |
| `start_date` | string | Yes | 

`YYYY-MM-DD`.

 |
| `tenant_name` | string | Yes |  |
| `tenant_org_id` | integer | No | 

Optional link to the tenant's BrickFlow organization (a positive 32-bit integer). An id no organization holds stores no link.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created |
| 400 | Blank or oversize tenant\_name, unknown lease\_type, a date that is not ISO or an end before the start, a tenant\_org\_id that is not a positive 32-bit integer, a building\_iri that is not a building of this organization, or a space\_iri that is not inside it |
| 401 | Not authenticated |
| 403 | Your role cannot modify leases, or the lease's space (else building) is outside your granted Leases write scope |
| 500 | Error reading the graph or writing the lease |

PUT `/leases/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
lease id

 |

#### Request body

application/json, required.

Body of `POST /api/v1/leases` and `PUT /api/v1/leases/{id}`: the whole lease, every time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `building_iri` | string | Yes | 
A building of this organization (full IRI).

 |
| `end_date` | string | No | 

`YYYY-MM-DD`, on or after `start_date`; omit or `null` for open-ended.

 |
| `lease_type` | string | Yes | 

One of `gross`, `net`, `modified_gross`, `triple_net`, `other`.

 |
| `space_iri` | string | No | 

A floor, room or space inside `building_iri`; omit or `null` for the whole building.

 |
| `start_date` | string | Yes | 

`YYYY-MM-DD`.

 |
| `tenant_name` | string | Yes |  |
| `tenant_org_id` | integer | No | 

Optional link to the tenant's BrickFlow organization (a positive 32-bit integer). An id no organization holds stores no link.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Updated |
| 400 | Same validation as POST |
| 401 | Not authenticated |
| 403 | Your role cannot modify leases, or either the stored lease's or the new target (space, else building) is outside your granted Leases write scope |
| 404 | No lease with this id in your organization |
| 500 | Error reading the graph or writing the lease |

DELETE `/leases/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
lease id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Deleted |
| 401 | Not authenticated |
| 403 | Your role cannot modify leases, or the stored lease's space (else building) is outside your granted Leases write scope |
| 404 | No lease with this id in your organization |
| 500 | Error reading the graph or deleting the lease |

## Surveys and custom records (16)

GET `/record-types`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The record types defined by shape files in ontology/shapes that the caller may read, with their fields |
| 401 | Not authenticated (no session and no valid API token) |

GET `/records/{type}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | Yes | string.
the record type's name, from /api/v1/record-types

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every record of the type in the caller's organization: BrickFlow ID, field values and each source's own IDs |
| 401 | Not authenticated |
| 403 | A scoped caller (limited to specific buildings) and the type's shape does not say gk:scopedRead |
| 404 | No such record type |
| 500 | The records could not be read |

POST `/records/{type}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | Yes | string.
the record type's name

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `values` | object | Yes | 
Field key to value; blank removes the value.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created, with its new BrickFlow ID |
| 400 | The values break the shape's rules: the body lists each problem and how to fix it |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or it is limited to specific buildings |
| 404 | No such record type |
| 500 | The record could not be saved or checked |

GET `/records/{type}/{id}`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | Yes | string.
the record type's name

 |
| `id` | path | Yes | string.

the BrickFlow ID, BF-XXXXX-XXXXX

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The record with its field values and each source's own IDs |
| 401 | Not authenticated |
| 403 | A scoped caller and the type's shape does not say gk:scopedRead |
| 404 | No such record type, or no record with this BrickFlow ID in your organization |
| 500 | The record could not be read |

PUT `/records/{type}/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | Yes | string.
the record type's name

 |
| `id` | path | Yes | string.

the BrickFlow ID, BF-XXXXX-XXXXX

 |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `values` | object | Yes | 
Field key to value; blank removes the value.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Updated: the values sent replace the record's values |
| 400 | The values break the shape's rules: the body lists each problem and how to fix it |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or it is limited to specific buildings |
| 404 | No such record type, or no record with this BrickFlow ID in your organization |
| 500 | The record could not be saved or checked |

GET `/records/{type}/checks`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | Yes | string.
the record type's name

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The records that break the shape's rules, each with what is wrong; an empty list means every record passed |
| 401 | Not authenticated |
| 403 | A scoped caller and the type's shape does not say gk:scopedRead |
| 404 | No such record type |
| 500 | The records could not be read or the check could not run; this is never answered as an empty list |

GET `/records/{type}/export`

Any API token

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | Yes | string.
the record type's name

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | CSV: BrickFlow ID, every field, then one column per source ID scheme. Never internal addresses or row ids |
| 401 | Not authenticated |
| 403 | A scoped caller and the type's shape does not say gk:scopedRead |
| 404 | No such record type |
| 500 | The records could not be read |

POST `/records/{type}/import`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | Yes | string.
the record type's name

 |
| `source` | query | No | string.

a name for the file's origin, kept beside each Source ID

 |
| `Idempotency-Key` | header | No | string.

Optional, 1 to 200 characters. Send the same value when retrying this import (a lost response, a timeout): the first call's answer comes back and nothing is imported twice. Use a new value for each new file. The answer to a repeat carries the header `Idempotent-Replayed: true`. The same value on a different file answers 422.

 |

#### Request body

text/csv, required. string

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | How many rows were created and updated, which rows need a person to confirm a match first, and which rows broke the shape |
| 400 | The file itself cannot be imported (no header, an unknown column, unreadable CSV); nothing was changed |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or it is limited to specific buildings |
| 404 | No such record type |
| 413 | The file is over 5 MB |
| 500 | The records could not be saved or checked |

GET `/schemas`All form schemas plus the derived document-type registry, in one fetch.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every form schema reduced from ontology/shapes and ontology/forms, plus the registered extraction document types. Identical for every caller; ETag'd by content |
| 304 | Not modified (If-None-Match matched) |
| 401 | Not authenticated |
| 403 | User not registered |

GET `/surveys`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every live questionnaire this organization has authored, and every response to any of them (archived questionnaires' responses included) |
| 401 | Not authenticated |
| 403 | Your access is limited to specific buildings. Ask an owner or admin for access. |

POST `/surveys/groups`

Token that can change data

#### Request body

application/json, required.

The create and the edit body, one struct, so the two paths cannot drift apart in which fields they carry.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cadence` | string | Yes |  |
| `description` | string | No |  |
| `expected_updated_at` | string | No | 
RFC3339, from the group's own `updated_at`. Required on `PUT` (a 400 without it); ignored on `POST`, which has nothing to collide with.

 |
| `name` | string | Yes |  |
| `place_iri` | string | No | 

Where the questionnaire sits: a building, space or site of this organization. Null is the whole organization, which only a person who sees the whole organization may author. On `PUT`, absent leaves the place as it is.

 |
| `questions` | any | Yes | 

A JSON array of question objects; `[]` for a questionnaire with no questions yet. Required rather than defaulted: an ABSENT array and an empty one would otherwise both save an empty questionnaire, and one of those is a client bug that must surface.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Created |
| 400 | Blank name, unknown cadence, or a question BrickFlow cannot show (the body names it) |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access |

PUT `/surveys/groups/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
survey\_group id

 |

#### Request body

application/json, required.

The create and the edit body, one struct, so the two paths cannot drift apart in which fields they carry.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cadence` | string | Yes |  |
| `description` | string | No |  |
| `expected_updated_at` | string | No | 
RFC3339, from the group's own `updated_at`. Required on `PUT` (a 400 without it); ignored on `POST`, which has nothing to collide with.

 |
| `name` | string | Yes |  |
| `place_iri` | string | No | 

Where the questionnaire sits: a building, space or site of this organization. Null is the whole organization, which only a person who sees the whole organization may author. On `PUT`, absent leaves the place as it is.

 |
| `questions` | any | Yes | 

A JSON array of question objects; `[]` for a questionnaire with no questions yet. Required rather than defaulted: an ABSENT array and an empty one would otherwise both save an empty questionnaire, and one of those is a client bug that must surface.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Saved |
| 400 | Blank name, unknown cadence, a question BrickFlow cannot show, or a missing/unparseable expected\_updated\_at |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access |
| 404 | No live questionnaire with this id in your organization |
| 409 | Somebody else saved this questionnaire first, or its cadence cannot change now that a period has been answered |

DELETE `/surveys/groups/{id}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
survey\_group id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Retired. Nothing is deleted: the questionnaire leaves the page and every answer given to it stays, exportable |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access |
| 404 | No live questionnaire with this id in your organization |

PATCH `/surveys/groups/{id}/responses/{period}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
survey\_group id

 |
| `period` | path | Yes | string.

The period label the cadence allows, 2026 (Annual), 2026-Q1 (Quarterly), once (One-time)

 |

#### Request body

application/json, required.

`PATCH /groups/{id}/responses/{period}`, the questions this request changes, and nothing else.

A patch, rather than the whole sheet, IS the collaboration model: two people answering different questions in the same period are editing one row (`survey_response_period_unique`), and a whole-sheet PUT would make each save overwrite whatever the other had just written.sql`.`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `remove` | list of string | No | 
The question ids to clear. Absent is empty, clearing nothing is the ordinary case, so it is not a client bug worth surfacing.

 |
| `set` | any | No | 

Question id -> answer. A JSON OBJECT: anything else is a 400 rather than a merge, because Postgres' `jsonb || jsonb` with an array on the right REPLACES the whole sheet with that array, one malformed request would otherwise destroy every answer in the period. The table's `survey_response_answers_object` CHECK is the second guard.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The period's sheet as it now stands, with this patch merged in |
| 400 | A `set` that is not an object, an answer past the size caps, or a period the group's cadence does not allow (the body names it) |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access |
| 404 | No live questionnaire with this id in your organization |
| 409 | This period's answers have been submitted, or the questionnaire was retired, reopen or reload |

POST `/surveys/groups/{id}/responses/{period}/reopen`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
survey\_group id

 |
| `period` | path | Yes | string.

The period label whose sheet is being reopened

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | A draft again, editable; what it looked like before is in the audit log |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access |
| 404 | No submitted answers for this period in your organization, or its questionnaire has been retired |

POST `/surveys/groups/{id}/responses/{period}/submit`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
survey\_group id

 |
| `period` | path | Yes | string.

The period label whose sheet is being submitted

 |

#### Request body

application/json, required.

`POST /groups/{id}/responses/{period}/submit`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_updated_at` | string | No | 
RFC3339, from the GROUP's `updated_at` as the client last read it. Required (a 400 without it): a submit stores the questions the answers belong to, and submitting without saying which version was on screen is how a sheet ends up snapshotted against questions nobody was asked.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Submitted, carrying the questions it was answering |
| 400 | A missing/unparseable expected\_updated\_at, a required question with no answer, or an answer that is not one of the options (the body names the question ids) |
| 401 | Not authenticated |
| 403 | Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access |
| 404 | No questionnaire with this id in your organization, or nothing answered for this period yet |
| 409 | Already submitted, or the questionnaire changed since you loaded it |

## Reference data (4)

GET `/release`The release this server is running: the full commit, the PR it came in with, the commit's subject and when the image was built. Any signed-in person may read it (it is what the app's footer shows); the signed-out \`/readyz\` shows the short commit and PR number only.

Any API token, also Read reports only

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The release this server is running; a field the build did not record is null |
| 401 | Not authenticated, or an invalid, revoked or expired API token |
| 402 | The organization's subscription has ended |
| 403 | User not registered |
| 500 | The caller could not be resolved |

GET `/vocab`The effective vocabulary (seed tier), one fetch per session.

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Commodity concept terms, exact aliases (lowercased), and prefix rules in match order, the resolution semantics are: trim+lowercase, exact alias first, longest prefix second, otherwise unmapped (never a guess) |
| 304 | Not modified (If-None-Match matched) |
| 401 | Not authenticated |
| 403 | User not registered |

GET `/vocab/questions`

Any API token

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The org's open vocabulary questions, each with ranked candidates from the deterministic proposal engine |
| 401 | Not authenticated |
| 403 | User not registered, or a scoped role |

POST `/vocab/questions/{id}/answer`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64). |

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `canonical_term` | string | Yes | 
The canonical concept IRI the human confirmed.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Decision minted (key\_code pinned), question closed, and one deterministic follow-up job per holding sync run over its pinned bytes, the response lists the follow-up job ids and their statuses. A period the platform already holds a different value for keeps the saved value: the new one is held until someone with edit rights chooses to replace it or keep the saved value. `periods_already_filled` lists up to 50 such periods, each with the saved and the new value and the meter and building by name, and `readings_set_aside` counts all of them (null when they could not be read back) |
| 400 | Unknown concept IRI |
| 401 | Not authenticated |
| 403 | User lacks owner/admin role |
| 404 | No such open question in this organization |
| 409 | A job holding the spelling is a workbook upload for an organization whose one-time building rename has not run yet; its follow-up would be refused, so the question stays open and nothing is written. Answer again once the rename has run |

## Config (1)

GET `/config/status`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Every optional feature and whether this deployment has it configured. Variable names only, never values |
| 401 | Not authenticated |
| 403 | Not an owner or admin of the active organization |
| 500 | The utility provider registry could not be read |

## Legal policies (1)

GET `/legal-policies/current`

Token that can change data

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | ca address and full text |
| 401 | Not authenticated |
| 404 | Staff have not published both policies yet. The body says so in plain text |
| 500 | The policies could not be read |

## Pilot invite (1)

GET `/pilot-invite/{token}`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `token` | path | Yes | string.
The token from the emailed link

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The answers the setup wizard pre-fills |
| 404 | The link is unknown, expired or already used |

## Staff (7)

GET `/staff/feedback`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `status` | query | No | string.
`open` (the default), `ready_for_review`, `fixed`, `wont_fix` or `all`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Up to 500 notes, newest first, without their pictures |
| 400 | An unknown status filter: use open, ready\_for\_review, fixed, wont\_fix or all |
| 401 | Not authenticated |
| 403 | Not BrickFlow staff (or staff access is not configured) |
| 500 | The notes could not be read |

GET `/staff/feedback/{id}/screenshot`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | Yes | integer (int64).
The note's id

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The PNG of the element |
| 401 | Not authenticated |
| 403 | Not BrickFlow staff (or staff access is not configured) |
| 404 | No such note, or it was saved without a picture |
| 500 | The picture could not be read |

GET `/staff/feedback/export`

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `status` | query | No | string.
`open` (the default), `ready_for_review`, `fixed`, `wont_fix` or `all`.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Notes newest first, each with its picture as base64 PNG, as a downloadable JSON file. At most 500 notes and 40 MB of pictures; `truncated` says when more matched |
| 400 | An unknown status filter: use open, ready\_for\_review, fixed, wont\_fix or all |
| 401 | Not authenticated |
| 403 | Not BrickFlow staff (or staff access is not configured) |
| 500 | The notes could not be read |

POST `/staff/legal-policies`Publish one version by hand.json\` daily (\`legal\_policy\_sync\`); this endpoint stays as the fallback when the site cannot be reached, and a version it stores carries the staff caller as its publisher.

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `body` | string | Yes | 
The policy text; not empty.

 |
| `kind` | string | Yes | 

`privacy` or `security`.

 |
| `url` | string | Yes | 

ca address of this version; must start with `https://`.

 |
| `version_date` | string | Yes | 

`YYYY-MM-DD`; not later than today (UTC).

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 201 | The version is stored. `current` says whether it is now the newest of its kind |
| 400 | Unknown kind, a body that is empty after trimming, an address not starting with https://, a malformed date, or a version date later than today (UTC). The body says which |
| 401 | Not authenticated |
| 403 | Not BrickFlow staff (or staff access is not configured) |
| 409 | That kind already has a version with that date. Versions are never edited: publish the correction under a new version date |
| 500 | The version could not be stored |

GET `/staff/paid-calls`Every organization's counts and the estimated spend, for BrickFlow staff.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `month` | query | No | string.
`YYYY-MM`; this month when left out.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The month's global figure per Google service with the estimated spend, and each organization's counted calls |
| 400 | `month` is not YYYY-MM |
| 401 | Not authenticated |
| 403 | Not BrickFlow staff (or staff access is not configured) |
| 500 | The counts could not be read |

POST `/staff/test-members`Make or reset a test member in a test organization (BrickFlow staff only).

Token that can change data

#### Request body

application/json, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `buildings` | list of string | No | 
For a scoped role (limited\_editor, limited\_viewer, contractor, tenant): the buildings (or spaces, meters) of this organization the member may read, as IRIs. Replaces every grant the member had. Ignored for an organization-wide role.

 |
| `email` | string | Yes | 

com`.`

 |
| `label` | string | No | 

g. "invite rehearsal". At most 60 characters.

 |
| `organization_id` | integer | Yes | 

A test organization (its `is_test_organization` flag is set).

 |
| `own_organization` | boolean | No | 

Also give the member an organization of their own, as a brand-new sign-up has, marked as a test organization with its setup not done. The key is then made for that organization (it is the `organization_id` answered); `organization_id` in the request stays the test organization that vouches for the member.

 |
| `restart_onboarding` | boolean | No | 

Clear the member's setup answers (persona, goals, the onboarded mark) so their next sign-in starts at the first-run screens again.

 |
| `role` | string | Yes | 

One of owner, admin, editor, viewer, limited\_editor, limited\_viewer, contractor, tenant.

 |
| `sample_green_button_account` | boolean | No | 

Put one sample Green Button account, waiting for its choice, in `organization_id`, so the choose screen can be looked at. It holds no token and is never synced. Needs the `london-hydro` utility.

 |
| `ttl_minutes` | integer | No | 

How long the key lives: 5 to 240 minutes, default 60.

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | The test member exists with the requested role and a new short-lived automation key; every earlier key of the member is revoked |
| 400 | The body is not valid, the role is unknown, or the address is not a test mail address |
| 401 | Not authenticated |
| 403 | Not BrickFlow staff, or the organization is not marked as a test organization (including one that does not exist) |
| 404 | No such organization |
| 409 | A real account already holds that address |
| 500 | The test member could not be made |

GET `/staff/users/inactive`People who have not signed in for N days, for BrickFlow staff.

Token that can change data

#### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `days` | query | No | integer (int64).
Inactive for at least this many days.=3650

 |

#### Replies

| Status | Meaning |
| --- | --- |
| 200 | Users whose newest recorded sign-in is older than `days` days, or who have none recorded, oldest first with the unrecorded first; at most 500, `truncated` says when there were more. A null `last_active_at` means no sign-in recorded since `records_since`. |
| 400 | `days` is not a whole number |
| 401 | Not authenticated |
| 403 | Not BrickFlow staff (or staff access is not configured) |
| 500 | The list could not be read |
