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 Authorizationheader: Authorization: Bearer YOUR_TOKEN. Paths below start after /api/v1. Create a token and read about errors 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 (46)
- Buildings (25)
- Spaces and equipment (17)
- Meters and readings (31)
- Bills (27)
- Emissions and reports (24)
- Alerts (21)
- Targets (26)
- ENERGY STAR Portfolio Manager (6)
- Green Button (6)
- Connected sources (26)
- Documents (10)
- Leases (4)
- Surveys and custom records (16)
- Reference data (4)
- Config (1)
- Legal policies (1)
- Pilot invite (1)
- Staff (7)
Portfolio and organization (46)
GET/entities/provenanceWho 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/orgRenames 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-ownersentity_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-grantsgrants` 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/onboardingSelf-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-cards1-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-grantsThe 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-perspectiveDeclares 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-visibilitySwitches 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-buildingsReport 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-linksThe 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-linksDecide 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-historymonth=` 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/reparentIts 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-matchesThe 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}/dismissDismiss 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/scanRun 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-monthlyWhether 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-monthlyMarks 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-monthlyForgets 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/calculatedA 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-conflictsThe 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}/resolveSettles 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}/correctionsWhat 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-profilePeak 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-seriesThe 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}/readingsA 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}/unitA 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}/unitCorrects 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/previewPreviews 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/intervalsHow 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/provenanceThe 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/discrepanciesThe 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/chargesWhat 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/demandEvery 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-historyEvery 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-invoiceslimit` 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-invoicesManual 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}/correctionsWhat 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/downloadsRecords 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/projectsLists 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/projectsCreates 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-buildingsproperty_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/notificationA 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-requestsThis 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-requestsSuggest 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}/upvoteCast 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}/upvoteRetract 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}/retry6-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/resolveOne 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/schemasAll 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/releaseThe 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/vocabThe 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-policiesPublish 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-callsEvery 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-membersMake 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/inactivePeople 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 |