Developers

BrickFlow API reference

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

Before you start

Every request goes to https://app.brickflow.site/api/v1 over HTTPS with your token in the 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)

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

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

StatusMeaning
200Whether a connector minted this record, and which
400iri outside this org
401Not authenticated
403User not registered
GET/graph/export

Any API token

Parameters

NameInRequiredDescription
formatqueryNostring.
"turtle" (default) or "rdfxml".

Replies

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

Any API token

Replies

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

Any API token

Replies

StatusMeaning
200Caller'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
401Not authenticated
GET/graph/stats

Any API token

Replies

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

Token that can change data

Replies

StatusMeaning
200The Getting started steps the caller finished
401Not authenticated
500The steps could not be read
PUT/me/getting-started/{step}

Token that can change data

Parameters

NameInRequiredDescription
steppathYesstring.
The step name: lowercase letters, digits and dashes

Replies

StatusMeaning
200The step is marked finished for the caller
400The step name is not valid
401Not authenticated
500Not saved
GET/me/later-questions

Token that can change data

Replies

StatusMeaning
200The questions the caller answered or put away in this organization
401Not authenticated
500Not read
PUT/me/later-questions/{key}

Token that can change data

Parameters

NameInRequiredDescription
keypathYesstring.
The question's id

Request body

application/json, required.

FieldTypeRequiredDescription
answerstringNo
The picked choice's id, or null for Not now.

Replies

StatusMeaning
204Saved; a question already answered keeps its first answer
400The question or choice id is not a short lowercase slug
401Not authenticated
500Not saved
GET/me/notification-pref

Token that can change data

Replies

StatusMeaning
200The caller's own notification preference
401Not authenticated
403User not registered
PUT/me/notification-pref

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
modestringYes
"off" | "daily" | "immediate".

Replies

StatusMeaning
200Preference saved
400Unknown mode
401Not authenticated
403User not registered
POST/me/pilot-invite/claim

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
tokenstringYes

Replies

StatusMeaning
200Answers 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
401Not authenticated
GET/me/setup-emails

Token that can change data

Replies

StatusMeaning
200Whether the setup emails concern the caller, and their choice
401Not authenticated
403User not registered
PUT/me/setup-emails

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
subscribedbooleanYes

Replies

StatusMeaning
200Choice saved
401Not authenticated
403User not registered
GET/me/tour-progress

Token that can change data

Replies

StatusMeaning
200Where the caller left the welcome tour; progress is null when never started
401Not authenticated
500The progress could not be read
PUT/me/tour-progress

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
finishedbooleanNo
stepintegerYes

Replies

StatusMeaning
200Saved for the caller
400The step is not a number from 0 to 99
401Not authenticated
500Not saved
GET/modules

Any API token, also Read reports only

Replies

StatusMeaning
200Registered calculation modules
401Not authenticated
403User not registered
GET/modules/{id}/meter-control

Any API token

Parameters

NameInRequiredDescription
idpathYesstring.
g. ghg-scope12)
buildingqueryYesstring.
Full building IRI, URL-encoded.

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesstring.
Module id
buildingqueryYesstring.
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.

FieldTypeRequiredDescription
changeslist of objectYes
changes[].controlstringNoOne 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_iristringYes

Replies

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

Any API token

Parameters

NameInRequiredDescription
idpathYesstring.
g. eui-site, ghg-scope12)
buildingqueryNostring.
Full building IRI, URL-encoded. Omitted: the org-wide response.

Replies

StatusMeaning
200building 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
400building is present but not a valid IRI
401Not authenticated
403A scoped member with no grant in this report's domain
404Unknown module id
PATCH/modules/{id}/meter-inclusion

Token that can change data

Parameters

NameInRequiredDescription
idpathYesstring.
Module id
buildingqueryYesstring.
Full building IRI, URL-encoded.

Request body

application/json, required. list of object

Replies

StatusMeaning
200Overrides 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
400Invalid building IRI, unknown module id, or a meter_iri not among this building's carrier-classified meters for this module
401Not authenticated
403An 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

NameInRequiredDescription
idpathYesstring.
g. ghg-scope12)
fromqueryYesstring.
g. 2024-01-01T00:00:00Z).
toqueryYesstring.
Exclusive period end, RFC 3339.
compare_fromqueryNostring.
Optional compare-period start (RFC 3339); requires compare_to.
compare_toqueryNostring.
Optional compare-period end (RFC 3339); requires compare_from.
unitqueryNostring.
ts's display-unit menus.
area_unitqueryNostring.
Optional caller-selected output area-unit override (ft2/m2), eui-site's intensity denominator only; ignored by other modules.
factors_as_ofqueryNostring.
1-002), so a report made before a value was changed can be reproduced. Absent, the values in force now.
by_carrierqueryNoboolean.
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.
monthsqueryNoboolean.
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_scopequeryNoboolean.
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.
buildingqueryNostring.
Full building IRI: keep only that building's rows (the dashboard's building filter).
fuelqueryNostring.
): keep only that fuel's per-fuel rows (the dashboard's fuel filter).

Replies

StatusMeaning
200Results 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.
400Invalid from/to/compare_from/compare_to
401Not authenticated
403User not registered, or a scoped role with no Sustainability grant
404Unknown module id
GET/org

Any API token

Replies

StatusMeaning
200The active org, the caller's role, and (for org-wide roles) the member list
401Not authenticated
403User 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.

FieldTypeRequiredDescription
namestringYes

Replies

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

Token that only reads

Replies

StatusMeaning
200Pending access requests
403Only owners and admins
GET/org/audit

Any API token

Replies

StatusMeaning
200The 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
403Only owners and admins can read the audit log
GET/org/audit-log

Token that can change data

Parameters

NameInRequiredDescription
personqueryNostring.
A person's name, as the list shows it.
record_typequeryNostring.
A record type's name, as the list shows it ("Bill").
fromqueryNostring.
First day, YYYY-MM-DD, inclusive.
toqueryNostring.
Last day, YYYY-MM-DD, inclusive.
limitqueryNointeger (int64).
offsetqueryNointeger (int64).

Replies

StatusMeaning
200Data changes newest first, with the counts and filter choices the screen shows
400A date is not year-month-day
403Only 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

NameInRequiredDescription
batch_idpathYesinteger (int64).
The corrections_ref of an Audit log row
fromqueryNostring (date-time).
Only readings whose period starts at or after this time (RFC 3339). Meters only.
toqueryNostring (date-time).
Only readings whose period starts at or before this time (RFC 3339). Meters only.
limitqueryNointeger (int64).
Corrections per page, 1 to 500; 100 when absent.
offsetqueryNointeger (int64).

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
personqueryNostring.
A person's name, as the list shows it.
record_typequeryNostring.
A record type's name, as the list shows it ("Bill").
fromqueryNostring.
First day, YYYY-MM-DD, inclusive.
toqueryNostring.
Last day, YYYY-MM-DD, inclusive.
limitqueryNointeger (int64).
offsetqueryNointeger (int64).

Replies

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

Token that only reads

Replies

StatusMeaning
200Pending edit-access requests
403Only owners and admins
GET/org/edit-access-requests/mine

Token that only reads

Replies

StatusMeaning
200Whether the caller has a request waiting: {pending}
401Sign in first
GET/org/entity-access-requests

Token that only reads

Replies

StatusMeaning
200Pending entity-specific access requests
403Only 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

NameInRequiredDescription
entity_iriqueryYesstring.
The entity whose recorded owners to resolve

Replies

StatusMeaning
200Recorded owners that are linked BrickFlow organizations
400Missing entity_iri, or one outside this organization
401Not authenticated
403Only owners and admins
GET/org/grantable-owners-org-wide

Any API token

Replies

StatusMeaning
200Recorded owners, org-wide, that are linked BrickFlow organizations with no share issued yet
401Not authenticated
403Only owners and admins
GET/org/graph-entities

Any API token

Replies

StatusMeaning
200Every entity in this org's graph, flat, for the permissions builder's tree picker
403Only owners and admins
GET/org/members/{membership_id}/grants

Token that only reads

Parameters

NameInRequiredDescription
membership_idpathYesinteger (int64).

Replies

StatusMeaning
200The member's grant rows
403Only owners and admins
404No 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

StatusMeaning
200The places the caller was granted, one row per entity; empty for an org-wide role
401Not authenticated
403User not registered
500The 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.

FieldTypeRequiredDescription
goalslist of stringNo
1). Absent keeps what is stored.
join_pathstringNo
json). Absent keeps what is stored.
personastringNo
planned_sourceslist of stringNo
The data sources the member plans to bring. Absent keeps what is stored.
start_goalstringNo
The goal marked "start here"; must be one of goals.

Replies

StatusMeaning
200Onboarding recorded for the caller's own membership
400Persona over the stored column's length
401Not authenticated
403User 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.

FieldTypeRequiredDescription
discover_closedbooleanNo
true closes the Discover line that follows a finished set-up; false opens it again. Absent keeps what is stored.
setup_hiddenbooleanNo
true hides Home's "Get set up" card for this member in this organization; false shows it again. Absent keeps what is stored.

Replies

StatusMeaning
200The caller's Home card choices in the active organization
401Not authenticated
403User not registered
404No membership in the active organization
GET/org/org-grantsThe granting organization's outgoing shares, newest first.

Token that only reads

Replies

StatusMeaning
200Every share this organization has issued, newest first
401Not authenticated
403Caller 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.

FieldTypeRequiredDescription
reporting_perspectivestringYes
"owner" or "occupier".

Replies

StatusMeaning
200The stored reporting perspective
400A spelling outside owner / occupier
401Not authenticated
403User not registered, or lacks owner/admin role
500Error 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.

FieldTypeRequiredDescription
tenants_see_building_areabooleanYes

Replies

StatusMeaning
200The stored value
400The body is not {"tenants_see_building_area": true|false}
401Not authenticated
403User not registered, or lacks owner/admin role
500Error 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.

FieldTypeRequiredDescription
labelstringYes
linked_org_idintegerNo
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

StatusMeaning
200Owner created and its provenance-carrying ingest job committed
400Empty/oversize label, or a linked_org_id that is not a positive 32-bit integer
401Not authenticated
403User not registered, or a building-scoped role (an owner attaches to no building, so it is outside every granted subtree)
500Database or ingest error
GET/portfolio/building-locations`GET /api/v1/portfolio/building-locations` -- the portfolio map's pin data.

Any API token

Replies

StatusMeaning
200Every 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
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The 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

StatusMeaning
200e. probably one physical building recorded twice. Empty means none detected, NOT that none exist
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The 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

StatusMeaning
200Portfolio-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
401Not authenticated
403User not registered
500The graph store did not answer a whole-organization count

Buildings (25)

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.

FieldTypeRequiredDescription
basisstringNo
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_iristringYes
building_b_iristringYes
decisionstringYes
confirmed, these two records are one building, or dismissed, they are two different buildings that happen to share an address.
primary_iristringNo
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

StatusMeaning
200The decision as stored; a second decision about the same pair replaces the first
400Unknown decision or basis, the same building twice, or a confirmation whose primary_iri is missing or is not one of the pair
401Not authenticated
403Only owners, admins and editors, org-wide
404One of the IRIs is not a building in this organization
409Confirming 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
500The organization's buildings, its stored decisions or its duplicate-meter decisions could not be read
GET/buildings/{id}/equipment

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Building database id
iriqueryNostring.
Full building IRI, URL-encoded, takes precedence over the path id.
monthqueryNostring.
Reporting month (YYYY-MM), see [EquipmentInfo::status_as_of].

Replies

StatusMeaning
200Building's equipment, optionally with each item's status as of a reporting month
400iri given but not a valid IRI, or month given but not a valid YYYY-MM
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
Building database id
iriqueryNostring.
Full building IRI, URL-encoded, takes precedence over the path id.

Replies

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

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Building database id
iriqueryNostring.
Full building IRI, URL-encoded, takes precedence over the path id.

Replies

StatusMeaning
200Building's floors, with room counts
400iri given but not a valid IRI
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The graph store did not answer the floor listing or the caller's granted scope
GET/buildings/{id}/meters

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Building database id
iriqueryNostring.
Full building IRI, URL-encoded, takes precedence over the path id.
extra_readingsqueryNostring.
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

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

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Building database id
iriqueryNostring.
Full building IRI, URL-encoded, takes precedence over the path id.

Replies

StatusMeaning
200ENERGY STAR Portfolio Manager-reported metrics for the building
400iri given but not a valid IRI
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The graph store did not answer the reported-metrics read
GET/buildings/{id}/summary

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Building database id
iriqueryNostring.
Full building IRI, URL-encoded, takes precedence over the path id.

Replies

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

Any API token

Parameters

NameInRequiredDescription
includequeryNostring.
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

StatusMeaning
200Area 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)
400include given with a value other than owners or control
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The 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

NameInRequiredDescription
iriqueryYesstring.
The building's full IRI.

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The building's full IRI.

Request body

application/json, required.

FieldTypeRequiredDescription
awarded_onstringNo
"YYYY-MM-DD".
certificate_refstringNo
certifying_bodystringNo
expires_onstringNo
"YYYY-MM-DD", not before awarded_on.
levelstringNo
pointsnumberNo
99 (a Fitwel score, LEED points).
rating_systemstringNo
The rating system or sub-type: BD+C, O+M. Free text; the form offers the usual ones.
schemestringYes
leed, boma_best, energy_star, well, fitwel, zero_carbon_building or other.
scheme_otherstringNo
Required (non-blank) when scheme is other, and refused for every other scheme.
versionstringNo
1, v5. Free text; the form offers the usual ones.

Replies

StatusMeaning
201Created
400A field is not valid; the body names it
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403Your role cannot modify this organization's data, or the building is outside your Sustainability write access
404The IRI is not a building of the caller's organization
500Saving the certification failed
PUT/buildings/certifications/{id}

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The building's full IRI.
idpathYesinteger (int64).
building_certification id

Request body

application/json, required.

FieldTypeRequiredDescription
awarded_onstringNo
"YYYY-MM-DD".
certificate_refstringNo
certifying_bodystringNo
expires_onstringNo
"YYYY-MM-DD", not before awarded_on.
levelstringNo
pointsnumberNo
99 (a Fitwel score, LEED points).
rating_systemstringNo
The rating system or sub-type: BD+C, O+M. Free text; the form offers the usual ones.
schemestringYes
leed, boma_best, energy_star, well, fitwel, zero_carbon_building or other.
scheme_otherstringNo
Required (non-blank) when scheme is other, and refused for every other scheme.
versionstringNo
1, v5. Free text; the form offers the usual ones.

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The building's full IRI.
idpathYesinteger (int64).
building_certification id

Replies

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

Any API token

Replies

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

Any API token

Parameters

NameInRequiredDescription
iriqueryNostring.
Full building IRI, URL-encoded.
fromqueryNostring.
building= answers it (RFC 3339).
toqueryNostring.
Exclusive end of the intensity period, RFC 3339.
perqueryNostring.
month: the intensity period is one Specific month, per month.

Replies

StatusMeaning
200building= 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.
400No building iri, or an invalid one
401Not authenticated, or an invalid, revoked or expired API token
GET/buildings/fact-history

Any API token

Parameters

NameInRequiredDescription
iriqueryYesstring.
The building's IRI.

Replies

StatusMeaning
200Every 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
400iri is not an IRI
401Not authenticated
403User not registered, or your access is limited to specific buildings and does not include this one
404The building is not a building of the caller's organization
500The history could not be read
GET/buildings/facts-as-of

Any API token

Parameters

NameInRequiredDescription
iriqueryYesstring.
The building's IRI.
atqueryNostring (date).
The day to read the building on (YYYY-MM-DD), the whole day counting. Omitted means today.

Replies

StatusMeaning
200What 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
400iri is not an IRI, or at is not a date
401Not authenticated
403User not registered, or your access is limited to specific buildings and does not include this one
404The building is not a building of the caller's organization
500The facts could not be read
GET/buildings/meter-counts

Any API token

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
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

StatusMeaning
200Occupancy set/cleared; a gk:ManualEntry job committed
400Invalid 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)
401Not authenticated
403User not registered, or outside their granted write scope
404iri does not exist in this org's graph, or does not name a building
500Database or ingest error
GET/certifications

Any API token

Replies

StatusMeaning
200Every 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)
401Not authenticated (no session and no valid API token)
402The organization's subscription has ended (subscription_inactive)
403User not registered
500Reading the certifications failed
GET/property-values

Any API token

Parameters

NameInRequiredDescription
buildingqueryNostring.
Only this building's records (full IRI, URL-encoded).

Replies

StatusMeaning
200Every 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
400building= is blank
401Not authenticated (no session and no valid API token)
402The organization's subscription has ended (subscription_inactive)
403building= the answer is an empty list)
500Error 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.

FieldTypeRequiredDescription
amountnumberYes
01 once rounded to the cent, below 10000000000000.
basisstringYes
One of appraisal, assessment, purchase_price, book_value, other.
building_iristringYes
A building of this organization (full IRI).
currencystringNo
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.
notestringNo
At most 1000 characters; blank is stored as null.
valued_onstringYes
YYYY-MM-DD, not after today. One value per building per date.

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
amountnumberYes
01 once rounded to the cent, below 10000000000000.
basisstringYes
One of appraisal, assessment, purchase_price, book_value, other.
building_iristringYes
A building of this organization (full IRI).
currencystringNo
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.
notestringNo
At most 1000 characters; blank is stored as null.
valued_onstringYes
YYYY-MM-DD, not after today. One value per building per date.

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
property value id

Replies

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

Spaces and equipment (17)

GET/equipment

Any API token

Parameters

NameInRequiredDescription
buildingqueryNostring.
Restrict to one building, a database id or a full building IRI.
monthqueryNostring.
Reporting month (YYYY-MM), see [EquipmentInfo::status_as_of].

Replies

StatusMeaning
200Equipment (optionally scoped to one building, optionally with each item's status as of a reporting month)
400building given but not a valid id/IRI, or month given but not a valid YYYY-MM
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The 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.

FieldTypeRequiredDescription
asset_tagstringNo
rec:assetTag, verbatim.
commissioned_bystringNo
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_datestringNo
rec:commissioningDate, an ISO YYYY-MM-DD date string.
equipment_classstringNo
g. "AHU", "Chiller", "VAV"), see gk_ingest::connectors::equipment_brick_class for the full curated list.
labelstringYes
location_iristringNo
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_daysintegerNo
Whole days between scheduled maintenance, rec:maintenanceInterval, formatted server-side as its xsd:duration lexical form.
part_of_iristringNo
g. a fan inside an AHU), composition, independent of location_iri's physical placement. Must name an in-org /equipment/ IRI.
statusstringNo
Operational lifecycle status, one of gk_ingest::connectors::EQUIPMENT_STATUSES. gk:equipmentStatus.
status_notestringNo
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_datestringNo
gk:warrantyEndDate, the last day under warranty, an ISO YYYY-MM-DD date string. Shown on the organization calendar.

Replies

StatusMeaning
200Equipment created and its provenance-carrying ingest job committed
400Empty/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
401Not authenticated
403User not registered
500Database or ingest error
PATCH/equipment

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Request body

application/json, required.

iri=<encoded>.

FieldTypeRequiredDescription
asset_tagstringNo
rec:assetTag, same absent/null/value contract.
commissioned_bystringNo
rec:commissionedBy, same absent/null/value contract.
commissioning_datestringNo
rec:commissioningDate (YYYY-MM-DD), same absent/null/value contract.
feeds_irislist of stringNo
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.
labelstringNo
location_iristringNo
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_daysintegerNo
rec:maintenanceInterval, as a whole day count, same absent/null/ value contract.
statusstringNo
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_notestringNo
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_datestringNo
gk:warrantyEndDate (YYYY-MM-DD), same absent/null/value contract.

Replies

StatusMeaning
200Equipment updated and its provenance-carrying ingest job committed
400No 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)
401Not authenticated
403User 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
404iri does not exist in this org's graph, or does not name equipment or a meter
500Database or ingest error
DELETE/equipment

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

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

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

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

Token that can change data

Request body

application/json, required.

Body of POST /api/v1/spaces.

FieldTypeRequiredDescription
address_line1stringNo
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_line2stringNo
citystringNo
countrystringNo
gross_areanumberNo
gross_area_unitstringNo
Unit gross_area was reported in, "ft2"/"m2" (any spelling gk_ingest::connectors::area_unit_iri resolves).
gross_building_areanumberNo
gk:grossBuildingArea, BOMA's Gross Building Area. Same eligibility and gross_area_unit sharing as gross_area.
gross_leasable_areanumberNo
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.
jurisdictionstringNo
kindstringYes
One of site/building/floor/space/room/campus/region, meter and equipment have their own endpoints (POST /api/v1/meters, POST /api/v1/equipment).
labelstringYes
parent_iristringNo
postal_codestringNo
regionstringNo

Replies

StatusMeaning
200Entity 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
400Unknown 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)
401Not authenticated
402A building past the Free plan's limit (error: free_plan_building_limit, message says what to do)
403User not registered, or (error: building_read_only) the parent is a read-only building
500Database or ingest error
PATCH/spaces

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
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.

FieldTypeRequiredDescription
address_line1stringNo
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_line2stringNo
chilled_water_generation_methodstringNo
gk:chilledWaterGenerationMethod -- same absent/null/value contract as jurisdiction.
citystringNo
countrystringNo
gross_areanumberNo
gross_area_unitstringNo
Independent of gross_area (same absent/null/value contract) so a mislabeled unit can be corrected without re-entering the value.
gross_building_areanumberNo
gk:grossBuildingArea, same absent/null/value contract as gross_area, and shares its gross_area_unit.
gross_leasable_areanumberNo
gk:grossLeasableArea, same absent/null/value contract as gross_area, and shares its gross_area_unit.
jurisdictionstringNo
labelstringNo
postal_codestringNo
regionstringNo
valid_fromstringNo
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

StatusMeaning
200Entity 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
400No 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)
401Not authenticated
403User not registered
404iri does not exist in this org's graph, or names a different kind of entity
500Database or ingest error
DELETE/spaces

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

StatusMeaning
200Entity deleted
400iri 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)
401Not authenticated
403User not registered
404iri does not exist in this org's graph, or names a different kind of entity
409The record is synced from a provider such as ENERGY STAR, so a delete would last only until the next sync recreates it
500Database or ingest error
GET/spaces/address

Any API token

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

StatusMeaning
200The node's rec:address parts; all null when it has none
400iri outside this org
401Not authenticated
403User not registered, or not allowed to edit this space
GET/spaces/area

Any API token

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

StatusMeaning
200The node's own rec:grossArea/gk:grossLeasableArea/gk:grossBuildingArea/gk:areaUnit, unconverted
400iri outside this org
401Not authenticated
403User not registered
POST/spaces/campus

Token that can change data

Request body

application/json, required.

POST /api/v1/spaces/campus body.

FieldTypeRequiredDescription
initial_memberobjectYes
Body of POST /api/v1/spaces.
initial_member.address_line1stringNo
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_line2stringNo
initial_member.citystringNo
initial_member.countrystringNo
initial_member.gross_areanumberNo
initial_member.gross_area_unitstringNo
Unit gross_area was reported in, "ft2"/"m2" (any spelling gk_ingest::connectors::area_unit_iri resolves).
initial_member.gross_building_areanumberNo
gk:grossBuildingArea, BOMA's Gross Building Area. Same eligibility and gross_area_unit sharing as gross_area.
initial_member.gross_leasable_areanumberNo
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.jurisdictionstringNo
initial_member.kindstringYes
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.labelstringYes
initial_member.parent_iristringNo
initial_member.postal_codestringNo
initial_member.regionstringNo
labelstringYes

Replies

StatusMeaning
200Campus and its first member created together in one ingest job
400kind is not building/site, an empty/oversize label, or a parent_iri outside this org
401Not authenticated
402The first member is a building past the Free plan's limit (error: free_plan_building_limit, message says what to do)
403User not registered, or not an org-wide writer
500Database or ingest error
GET/spaces/occupant

Any API token

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Request body

application/json, required.

iri=.

FieldTypeRequiredDescription
lease_idintegerNo
Required for tenant: a lease of the building this space sits in.
occupantstringYes
none, us or tenant.

Replies

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

Any API token

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Request body

application/json, required.

iri=<space>.

FieldTypeRequiredDescription
occupiedbooleanYes
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

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

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Request body

application/json, required.

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

FieldTypeRequiredDescription
new_parent_iristringYes
The new parent's graph IRI.

Replies

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

Any API token

Replies

StatusMeaning
200Org'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
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
500The graph store did not answer the space tree read

Meters and readings (31)

GET/data-coverage

Any API token

Parameters

NameInRequiredDescription
fromqueryYesstring.
First day, inclusive, YYYY-MM-DD.
toqueryYesstring.
Day after the last, exclusive, YYYY-MM-DD. Whole UTC months are counted, up to 60.
gapqueryNostring.
Narrow the building rows only (never the columns or the tiles): bills, area, emissions, unattached or unread.

Replies

StatusMeaning
200For 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.
400The dates are missing or out of order, the span is over 60 months, or gap is not one of bills, area, emissions, unattached, unread
401Not authenticated
403A person limited to some buildings with no Energy, Data sources or Sustainability access
500A read failed; nothing partial is returned
GET/meter-matchesThe org's proposed cross-source meter matches, newest first.

Any API token

Parameters

NameInRequiredDescription
statusqueryNostring.
open (default), confirmed, or dismissed.

Replies

StatusMeaning
200Proposed matches in the requested status
401Not authenticated
403Your access is limited to specific buildings and does not include meter matches
POST/meter-matches/{id}/confirm

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).

Request body

application/json, required.

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

FieldTypeRequiredDescription
kept_meter_iristringYes
Must equal meter_a_iri or meter_b_iri on the row.

Replies

StatusMeaning
200Match confirmed; the excluded meter is now excluded from every registered calculation module
400kept_meter_iri is neither meter_a_iri nor meter_b_iri on this row
401Not authenticated
403Only owners/admins/editors, org-wide
404No such proposed match in this org
409The 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

NameInRequiredDescription
idpathYesinteger (int64).

Replies

StatusMeaning
200Proposed match dismissed
401Not authenticated
403Only owners/admins/editors, org-wide
404No such proposed match in this org
409The 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

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

Token that can change data

Request body

application/json, required.

Body of POST /api/v1/meters.

FieldTypeRequiredDescription
building_iristringNo
The building this meter is rec:locatedIn, if any, an unattached meter is legal, and there is no Portfolio-stub fallback.
componentslist of objectNo
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_iristringYes
A meter of this organization, of the same energy type.
components[].signstringYes
"add" or "subtract".
effective_fromstringNo
The first month (YYYY-MM) the formula is in effect; absent reaches back to the start. Only with formula or components.
effective_tostringNo
The last month (YYYY-MM) the formula is in effect; absent is still in effect. Only with formula or components.
formulastringNo
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_virtualbooleanNo
g. an allocated share of another meter's reading).
labelstringYes
measures_iristringNo
The brick:meters measurement target (a building, space, campus, or portfolio), independent of building_iri's physical placement.
report_effectsobjectNo
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_irislist of stringNo
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_ofstringNo
g. a tenant panel submeter of a landlord main meter), if any.
utility_typestringYes
g. "electric"/"e", "gas"/"g", "water"/"w", the alias set of gk_ingest::connectors::meter_class.

Replies

StatusMeaning
200Meter created and its provenance-carrying ingest job committed
400Empty/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
401Not authenticated
403User not registered
500Database or ingest error
PATCH/meters

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Request body

application/json, required.

iri=<encoded>.

FieldTypeRequiredDescription
building_iristringNo
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.
componentslist of objectNo
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_iristringYes
A meter of this organization, of the same energy type.
components[].signstringYes
"add" or "subtract".
effective_fromstringNo
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_tostringNo
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_afterstringNo
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.
formulastringNo
Replaces the formula of a calculated virtual meter (see [CreateMeterRequest::formula]). Absent leaves it alone. Only a meter created with a formula takes it.
labelstringNo
report_effectsobjectNo
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_ofstringNo
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_numberstringNo
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_numberstringNo
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_typestringNo
). 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

StatusMeaning
200Meter updated and its provenance-carrying ingest job committed
400No 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)
401Not authenticated
403User not registered, or the meter or its new parent meter is outside your granted write scope
404iri does not exist in this org's graph, or does not name a meter
409utility_meter_number is already on another meter of this organization; the message names that meter
500Database or ingest error
DELETE/meters

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

StatusMeaning
200Meter deleted
400iri outside this org, or the delete was refused by the data-quality rulebook (JSON EditRefusal body)
401Not authenticated
403User not registered
404iri does not exist in this org's graph, or does not name a meter
409The 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
500Database or ingest error
GET/meters/billed-monthlyWhether one meter is marked as billed monthly.

Any API token

Parameters

NameInRequiredDescription
iriqueryYesstring.
The meter's IRI, as the meters read gives it.

Replies

StatusMeaning
200The meter's answer; false when nobody has answered
400iri is not a valid IRI
401Not authenticated
403Your access is limited to specific buildings and does not include this meter
500Reading the setting failed
PUT/meters/billed-monthlyMarks one meter as billed monthly, or as not.

Token that can change data

Parameters

NameInRequiredDescription
iriqueryYesstring.
The meter's IRI, as the meters read gives it.

Request body

application/json, required.

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

FieldTypeRequiredDescription
billed_monthlybooleanNo
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_intervalstringNoOne 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

StatusMeaning
200Saved; the meter's answer
400Neither 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
401Not authenticated
403Your role cannot modify this organization's data, or is limited to specific buildings
500Reading 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

NameInRequiredDescription
iriqueryYesstring.
The meter's IRI, as the meters read gives it.

Replies

StatusMeaning
204Cleared (also when there was nothing to clear)
400iri is not a valid IRI
401Not authenticated
403Your role cannot modify this organization's data, or is limited to specific buildings
500Clearing 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

NameInRequiredDescription
iriqueryYesstring.
The target entity's full IRI, URL-encoded.

Replies

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

Any API token

Replies

StatusMeaning
200Meters 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
401Not authenticated, or an invalid, revoked or expired API token
403User not registered, or limited to specific buildings and holding no grant for energy
500The 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

NameInRequiredDescription
statusqueryNostring.
open (default), kept_recorded, took_proposed or superseded.
limitqueryNointeger (int64).
At most this many rows, newest first (default 200, at most 1000).

Replies

StatusMeaning
200The 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.
400An unknown status ("status must be one of open, kept_recorded, took_proposed, superseded")
401Not authenticated (no session and no valid API token)
402The organization's subscription has ended (subscription_inactive)
403User not registered, or a role limited to specific buildings with no write access to any meter
500Reading 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

NameInRequiredDescription
idpathYesinteger (int64).
The reading conflict's id

Request body

application/json, required.

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

FieldTypeRequiredDescription
candidate_job_idintegerYes
job_id), so a choice never acts on a value that arrived after the list loaded.
choicestringYes
replace makes the new value the saved reading; keep keeps the saved one.

Replies

StatusMeaning
200Settled: the row is took_proposed or kept_recorded
400An unknown choice ("choice must be \"replace\" or \"keep\""); nothing changed
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered; a role that cannot edit; or a role limited to specific buildings choosing for a meter outside its granted write scope
404No such reading conflict in this organization
409Nothing 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.
500Saving 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

NameInRequiredDescription
meter_keyqueryNostring.
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_idqueryNointeger (int64).
id. Ignored when series_ids is set.
series_idsqueryNostring.
includequeryNostring.
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.
startqueryNostring (date-time).
Inclusive lower bound, RFC 3339.
endqueryNostring (date-time).
Exclusive upper bound, RFC 3339.

Replies

StatusMeaning
200Neither 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
400Malformed, empty, or over-limit series_ids
401Not authenticated
403User not registered
404No such series in this org
GET/series/{id}/correctionsWhat sources replaced on one meter's readings, newest first.

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The series id
fromqueryNostring (date-time).
Only readings whose period starts at or after this time (RFC 3339). Meters only.
toqueryNostring (date-time).
Only readings whose period starts at or before this time (RFC 3339). Meters only.
limitqueryNointeger (int64).
Corrections per page, 1 to 500; 100 when absent.
offsetqueryNointeger (int64).

Replies

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

NameInRequiredDescription
idpathYesinteger (int64).
The series id
startqueryNostring (date-time).
Inclusive start (RFC 3339); 365 days before end when absent.
endqueryNostring (date-time).
Exclusive end (RFC 3339); just after the latest reading when absent.
tzqueryNostring.
The IANA time zone hours and days are counted in; America/Toronto when absent.

Replies

StatusMeaning
200The 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)
400end is not after start, the window is longer than 366 days, or tz is not a time zone
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered
404No such series in your organization, or one your role cannot read
500Reading 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

NameInRequiredDescription
idpathYesinteger (int64).
The series id

Replies

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

NameInRequiredDescription
idpathYesinteger (int64).
The series id
beforequeryNostring (date-time).
Only readings strictly before this time (RFC 3339): the next_before of the previous page.
limitqueryNointeger (int64).
Readings per page, 1 to 500; 100 when absent.

Replies

StatusMeaning
200One 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered
404No such series in your organization, or one your role cannot read
500Reading the readings failed
GET/series/{id}/unitA series' billed unit, and who changed it before.

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The series id

Replies

StatusMeaning
200The unit now and every change made to it, newest first
401Not authenticated
403Your access is limited to specific buildings and does not include this meter
404No such series in your organization
500Reading 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

NameInRequiredDescription
idpathYesinteger (int64).
The series id

Request body

application/json, required.

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

FieldTypeRequiredDescription
fromstringYes
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.
unitstringYes
The unit to give the meter: a spelling BrickFlow can convert (an energy, volume or mass unit), such as therms or kcf.

Replies

StatusMeaning
200Changed; the unit now and its history
400The 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
401Not authenticated
403Your role cannot modify this organization's data, or is limited to specific buildings
404No such series in your organization
409The meter's unit is no longer from: someone changed it since it was opened
500Saving the change failed
POST/series/{id}/unit/previewPreviews a unit change.

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The series id

Request body

application/json, required.

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

FieldTypeRequiredDescription
unitstringYes
The unit the person is about to give the meter; checked exactly as the change checks it.

Replies

StatusMeaning
200The 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
400The 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
401Not authenticated
403Your role cannot modify this organization's data, or is limited to specific buildings
404No such series in your organization
500Computing the preview failed
GET/series/areas

Any API token

Replies

StatusMeaning
200Each readable series' spaces and their floor areas
401Not authenticated
403User not registered
500The 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

NameInRequiredDescription
series_idsqueryYesstring.
Comma-separated series ids, at most 200.

Replies

StatusMeaning
200Per 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
400Malformed, empty, or more than 200 series ids
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered
500Reading the readings failed
GET/series/monthly-digest

Any API token

Parameters

NameInRequiredDescription
series_idsqueryYesstring.
series_ids=.
windowsqueryYesstring.
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

StatusMeaning
200For 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.
400Malformed, empty, or over-limit series_ids or windows
401Not authenticated
403User not registered
500The 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

NameInRequiredDescription
series_idsqueryYesstring.
Comma-separated series ids (the same limit as GET /api/v1/series).
fromqueryYesstring (date-time).
Periods starting at or after this time (RFC 3339).
toqueryYesstring (date-time).
Periods starting before this time (RFC 3339).

Replies

StatusMeaning
200Per 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
400Malformed or over-limit series_ids, or a window that ends before it starts
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered
404A named series is not in your organization, or is one your role cannot read
500Reading the readings failed
GET/unit-interpretations

Any API token

Replies

StatusMeaning
200Every resolved spelling for the org
401Not authenticated
403User not registered
PUT/unit-interpretations

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
fuelstringYes
resolved_unitstringYes
unitstringYes

Replies

StatusMeaning
204Interpretation saved
400Malformed unit, fuel or resolved_unit
401Not authenticated
403User lacks owner/admin role
DELETE/unit-interpretations/{fuel}/{unit}

Token that can change data

Parameters

NameInRequiredDescription
fuelpathYesstring.
unitpathYesstring.

Replies

StatusMeaning
204Interpretation cleared; the reading reverts to excluded
401Not authenticated
403User lacks owner/admin role
GET/weather/bills

Any API token

Parameters

NameInRequiredDescription
idsqueryYesstring.
Comma-separated bill (utility_invoice) ids, at most 500.

Replies

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

Bills (27)

GET/discrepanciesThe org's flagged cross-source conflicts, newest first.

Any API token

Parameters

NameInRequiredDescription
statusqueryNostring.
open (default), resolved_incumbent, resolved_candidate, or dismissed.

Replies

StatusMeaning
200Flagged conflicts in the requested status
401Not authenticated
403User not registered
POST/discrepancies/{id}/resolve

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).

Request body

application/json, required.

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

FieldTypeRequiredDescription
choicestringYes
incumbent keeps what the graph records; candidate replaces it with the source's proposed value.

Replies

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

Any API token

Parameters

NameInRequiredDescription
categoryqueryNostring.
Filter to one bill category ("Facilities/Equipment" or "Services/Other"); omit for both

Replies

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

Token that can change data

Request body

application/json, required. list of object

Replies

StatusMeaning
200Created
400Empty 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
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings
GET/facility-bills/{id}

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
facility_bill id

Replies

StatusMeaning
200One bill
401Not authenticated
403Your access is limited to specific buildings
404No bill with this id in your organization
GET/fx/rates

Any API token, also Read reports only

Parameters

NameInRequiredDescription
currenciesqueryNostring.
Comma-separated ISO 4217 codes, 1 to 30, each three capital letters. CAD is allowed and answered as 1.

Replies

StatusMeaning
200Monthly and yearly average rates for the asked currencies; CAD is answered as 1 for every month and year stored
400currencies is missing, empty, names more than 30 codes, or has an entry that is not three capital letters
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered
500Reading the stored rates failed
GET/invoices/chargesWhat each meter's bills charged for, per month.

Any API token

Parameters

NameInRequiredDescription
startqueryYesstring (date-time).
Inclusive, RFC 3339.
endqueryYesstring (date-time).
Exclusive, RFC 3339.

Replies

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

Any API token

Parameters

NameInRequiredDescription
fromqueryNointeger (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

StatusMeaning
200Every 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
400from is not a whole number
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or lacks org-wide read access
500Reading 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

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

Any API token

Parameters

NameInRequiredDescription
meter_iriqueryYesstring.
The meter entity to read the bills of (a meter_iri of an invoice row).
account_numberqueryNostring.
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_numberqueryNostring.
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

StatusMeaning
200Every bill whose derived meter_iri equals the one asked for, newest first; an IRI that matches no bill answers an empty list
400meter_iri is missing
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or lacks org-wide read access
500Reading 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

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

Any API token

Replies

StatusMeaning
200Every confirmed rate for this org, with its tier/TOU schedule if any
401Not authenticated
403Scoped roles cannot view this org-wide report
PUT/reconciliation/rates

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
basisstringYes
currencystringYes
effective_fromstringYes
"YYYY-MM"
ratenumberYes
series_idintegerYes

Replies

StatusMeaning
200Rate confirmed (or corrected, for the same series + effective_from)
400Negative rate, unrecognized basis, blank currency, or a malformed effective_from
401Not authenticated
403User lacks owner/admin role
PUT/reconciliation/rates/tiers

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
basisstringYes
currencystringYes
effective_fromstringYes
"YYYY-MM"
series_idintegerYes
tierslist of objectYes
A CONTIGUOUS progressive schedule starting at 0 consumption -- see [validate_tiers] for the exact shape enforced.
tiers[].max_consumptionnumberNo
tiers[].min_consumptionnumberYes
tiers[].ratenumberYes

Replies

StatusMeaning
200Tiered rate schedule confirmed (replaces any prior tiers for this series + effective_from)
400Invalid basis/currency/effective_from, or the tier list isn't a contiguous progressive schedule starting at 0
401Not authenticated
403User lacks owner/admin role
PUT/reconciliation/rates/tou

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
basisstringYes
currencystringYes
effective_fromstringYes
"YYYY-MM"
series_idintegerYes
windowslist of objectYes
windows[].days_of_weekstringYes
"all" | "weekdays" | "weekends".
windows[].end_hourintegerYes
1-24, local clock hour (24 = midnight, end-exclusive).
windows[].ratenumberYes
windows[].start_hourintegerYes
0-23, local clock hour.
windows[].window_labelstringYes

Replies

StatusMeaning
200Time-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)
400Invalid basis/currency/effective_from, or an invalid window
401Not authenticated
403User lacks owner/admin role
GET/reconciliation/report

Token that can change data

Parameters

NameInRequiredDescription
fromqueryNostring.
Inclusive lower bound on period (YYYY-MM). Absent means unbounded.
toqueryNostring.
Inclusive upper bound on period (YYYY-MM). Absent means unbounded.
limitqueryNointeger.
Page size, 1 to 20,000. Absent means 20,000, every bill the read covers.
offsetqueryNointeger.
Bills to skip, newest first. Absent means 0.

Replies

StatusMeaning
200One 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.
401Not authenticated
403Your access is limited to specific buildings and does not include this report
500Database error
GET/reconciliation/settings

Any API token

Replies

StatusMeaning
200The org's default currency
401Not authenticated
403Scoped roles cannot view this org-wide report
PUT/reconciliation/settings

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
default_currencystringYes

Replies

StatusMeaning
200Default currency saved
400Currency is not a 3-letter code
401Not authenticated
403User lacks owner/admin role
GET/utility-budgets

Any API token

Parameters

NameInRequiredDescription
buildingqueryNostring.
Only this building's records (full IRI, URL-encoded).

Replies

StatusMeaning
200Every 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
400building= is blank
401Not authenticated (no session and no valid API token)
402The organization's subscription has ended (subscription_inactive)
403building= the answer is an empty list)
500Error 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.

FieldTypeRequiredDescription
amountnumberYes
At least 0 (a zero budget is allowed), below 10000000000000.
budget_yearintegerYes
2000-2100. One budget per building per year.
building_iristringYes
A building of this organization (full IRI).
currencystringNo
As for [PropertyValueRequest::currency].
notestringNo
At most 1000 characters; blank is stored as null.

Replies

StatusMeaning
200Created
400A 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403Your role cannot modify utility budgets, or the building is outside your granted Financial write scope
409This building already has a utility budget for that year
500Error reading the graph or writing the budget
PUT/utility-budgets/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
amountnumberYes
At least 0 (a zero budget is allowed), below 10000000000000.
budget_yearintegerYes
2000-2100. One budget per building per year.
building_iristringYes
A building of this organization (full IRI).
currencystringNo
As for [PropertyValueRequest::currency].
notestringNo
At most 1000 characters; blank is stored as null.

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
utility budget id

Replies

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

Any API token

Parameters

NameInRequiredDescription
fromqueryNointeger (int64).
Inclusive lower bound on end_date.
toqueryNointeger (int64).
Exclusive upper bound on start_date.
utilityqueryNostring.
g. "electric".
limitqueryNointeger (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.
offsetqueryNointeger (int64).
Bills to skip, newest first, 0 or more. Ignored without limit.

Replies

StatusMeaning
200The 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
400from, 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")
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or lacks org-wide read access
500Reading 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

NameInRequiredDescription
allow_duplicatequeryNoboolean.
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.
replacequeryNoboolean.
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_datedqueryNoboolean.
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_minutesqueryNointeger (int32).
getTimezoneOffset()); only names the period in a 409's message. Defaults to 0.

Request body

application/json, required. list of object

Replies

StatusMeaning
200Every 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
302Redirect to /subscription: the caller has no organization yet, or the batch is empty
400Malformed body, or 1000 or more bills in one batch
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403The caller's role cannot modify this organization's data
409A 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)
413The body is over the JSON size limit
500Reading 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

NameInRequiredDescription
idpathYesinteger (int64).
The bill's id
replaced_by_jobqueryNointeger (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

StatusMeaning
200The 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or not an owner or admin ("Only owners and admins can delete a bill")
404No bill with this id in this organization
409Nothing 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)
500Reading 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

NameInRequiredDescription
idpathYesinteger (int64).
The bill's record ID
fromqueryNostring (date-time).
Only readings whose period starts at or after this time (RFC 3339). Meters only.
toqueryNostring (date-time).
Only readings whose period starts at or before this time (RFC 3339). Meters only.
limitqueryNointeger (int64).
Corrections per page, 1 to 500; 100 when absent.
offsetqueryNointeger (int64).

Replies

StatusMeaning
200The 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or lacks read access to bills
404No such bill in your organization, or one your role cannot read
500Reading the history failed
GET/utility-invoices/{id}/detail

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The bill's record ID

Replies

StatusMeaning
200The 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or lacks org-wide read access
404No bill with this id in the organization (another organization's bill answers the same)
500Reading the bill's lines failed

Emissions and reports (24)

GET/disclosures

Any API token

Parameters

NameInRequiredDescription
limitqueryNointeger (int64).
=200.

Replies

StatusMeaning
200The organization's saved export snapshots, newest first, without their frozen outputs, factors or inputs
400limit is not a whole number
401Not authenticated
403User not registered
500Database error
POST/disclosures

Token that can change data

Request body

application/json, required.

Body of POST /api/v1/disclosures.

FieldTypeRequiredDescription
export_kindstringYes
g. "csv", kept separate from source so multiple export formats off the same surface stay distinguishable.
factorsanyNo
Methodology/citations/conversion factors applied in producing outputs, when the surface has any to freeze.
inputsanyNo
The raw values outputs were derived from, when the surface has something worth freezing beyond outputs itself.
outputsanyYes
The frozen figures as exported, shaped by source, opaque here.
period_fromstringYes
Inclusive period start, RFC 3339.
period_tostringYes
Exclusive period end, RFC 3339.
point_in_timebooleanNo
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.
sourcestringYes
g. "energy-report-csv".

Replies

StatusMeaning
200Disclosure snapshot frozen and persisted (append-only, this call never updates an existing row)
400Empty source/export_kind, invalid period_from/period_to, or period_to not after period_from
401Not authenticated
403User not registered
500Database error
GET/disclosures/{id}

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Disclosure snapshot id

Replies

StatusMeaning
200The saved export with its frozen outputs, factors and inputs exactly as stored
401Not authenticated
403User not registered
404No such snapshot in the caller's organization; another organization's id gets the same status and body
500Database 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.

FieldTypeRequiredDescription
filenamestringYes
The name the browser saved the file under (only its last segment is kept, at most 200 characters).

Replies

StatusMeaning
204downloaded
400No file name was sent
401Not signed in
403Not a member of the active organization
GET/energy/intensity

Any API token, also Read reports only

Parameters

NameInRequiredDescription
fromqueryYesstring.
g. 2025-01-01T00:00:00Z).
toqueryYesstring.
Exclusive end, RFC 3339.
perqueryNostring.
month: the dates are one Specific month, and the figure is per month, never scaled. Anything else, or absent: per year.
buildingqueryNostring.
Only this building's row, and a portfolio figure over it alone.
carriersqueryNostring.
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.
seriesqueryNostring.
Only the energy read from these series, comma separated ids: a screen narrowed to some meters.

Replies

StatusMeaning
200Site 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.
400The 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
401Not authenticated
403A person limited to some buildings with no Energy access
500A read failed; nothing partial is returned
GET/factor-catalog

Any API token

Replies

StatusMeaning
200Every 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
401Not authenticated
403User not registered
500Error reading the factor catalog
GET/factor-overrides

Any API token

Replies

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

Token that can change data

Request body

application/json, required.

A new value.

FieldTypeRequiredDescription
effective_fromstringYes
factor_keystringYes
A key from GET /api/v1/factor-catalog.
justificationstringYes
Why this value replaces the reference one. Required.
scope_iristringNo
The building, floor or room; absent for the organization.
scope_levelstringYes
"organization", "building", "floor" or "room".
valuenumberYes

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
factor value id

Request body

application/json, required.

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

FieldTypeRequiredDescription
effective_fromstringYes
justificationstringYes
valuenumberYes

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
factor value id

Replies

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

Any API token

Parameters

NameInRequiredDescription
buildingqueryNostring.
Full building IRI, URL-encoded. Without it, the whole portfolio the caller may see.
from_monthqueryNostring.
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_monthqueryNostring.
Last reading month of the page's banner (YYYY-MM, inclusive).

Replies

StatusMeaning
200What 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.
400building is not a valid IRI, or from_month/to_month is not a valid YYYY-MM, or from_month is after to_month
401Not authenticated, or an invalid, revoked or expired API token
403User not registered
GET/scope3-entries

Any API token

Parameters

NameInRequiredDescription
fromqueryNostring.
Inclusive period start: RFC 3339 or "YYYY-MM-DD" (its UTC date is used).
toqueryNostring.
EXCLUSIVE period end, in the same forms.

Replies

StatusMeaning
200The organization's lines overlapping [from, to), and category totals
400from or to missing or not a date, or to not after from
401Not authenticated (no session and no valid API token)
403This 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.

FieldTypeRequiredDescription
activity_amountnumberNo
Required for activity, zero or more.
activity_unitstringNo
).
categoryintegerYes
1, 6 or 7.
descriptionstringNo
factor_kg_co2e_per_unitnumberNo
Required for activity: kg CO2e per one unit, zero or more.
factor_sourcestringNo
Required for both methods: the factor's source, or the note for a typed figure.
methodstringNo
"activity" (amount x factor) or "tonnes" (typed directly).
period_endstringNo
"YYYY-MM-DD", not before period_start.
period_startstringNo
"YYYY-MM-DD".
place_iristringNo
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_co2enumberNo
Required for tonnes, zero or more. Ignored for activity (computed).

Replies

StatusMeaning
200Created
400A field is missing, blank, negative, too large or not valid; the body names it
401Not authenticated
403Your 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

NameInRequiredDescription
idpathYesinteger (int64).
scope3_manual_entry id

Request body

application/json, required.

FieldTypeRequiredDescription
activity_amountnumberNo
Required for activity, zero or more.
activity_unitstringNo
).
categoryintegerYes
1, 6 or 7.
descriptionstringNo
factor_kg_co2e_per_unitnumberNo
Required for activity: kg CO2e per one unit, zero or more.
factor_sourcestringNo
Required for both methods: the factor's source, or the note for a typed figure.
methodstringNo
"activity" (amount x factor) or "tonnes" (typed directly).
period_endstringNo
"YYYY-MM-DD", not before period_start.
period_startstringNo
"YYYY-MM-DD".
place_iristringNo
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_co2enumberNo
Required for tonnes, zero or more. Ignored for activity (computed).

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
scope3_manual_entry id

Replies

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

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
contentstringYes
The start of the file's text (the wizard sends at most 64 KiB).
filenamestringNo
The file's name: a Green Button name keeps the file away from Claude.

Replies

StatusMeaning
200What 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
400Empty content, an unreadable CSV, or no header row
401Not authenticated
403User not registered
413The content is over 256 KiB (the wizard sends at most the first 64 KiB)
GET/tabular/uploads

Any API token

Replies

StatusMeaning
200This organization's wizard uploads, newest first, lease files included
401Not authenticated (no session and no valid API token)
403User 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

NameInRequiredDescription
Idempotency-KeyheaderNostring.
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.

FieldTypeRequiredDescription
contentstringYes
The file's text, verbatim (CSV in v1).
data_typestringYes
filenamestringNo

Replies

StatusMeaning
200Bytes 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
400Unknown data type, empty content, or an unreadable CSV
401Not authenticated
403User not registered
429The 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

NameInRequiredDescription
idpathYesinteger (int64).
The upload's id

Request body

application/json, required.

FieldTypeRequiredDescription
currentlist of objectYes
current[].bandstringYes
decided | preselect | suggest | none.
current[].columnstringYes
current[].fieldstringNo

Replies

StatusMeaning
200Claude'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
400A current column that is not a header of the file, or an unknown field or band
401Not authenticated
403User not registered
404No such upload in the caller's organization
POST/tabular/uploads/{id}/confirm

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The upload's id
Idempotency-KeyheaderNostring.
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.

FieldTypeRequiredDescription
correctionslist of objectNo
corrections[].columnstringYes
corrections[].rowintegerYes
corrections[].valuestringYes
date_formatstringNo
decisionslist of objectNo
decisions[].canonical_termstringYes
The canonical concept IRI the user confirmed.
decisions[].dimensionstringYes
decisions[].raw_valuestringYes
mappingslist of objectYes
mappings[].columnstringYes
The file's column header, verbatim.
mappings[].fieldstringNo
Target field key, or null = "ignore this column".
overwriteslist of objectNo
A survey upload's answer to each overwrite it listed: replace or keep.
overwrites[].choicestringYes
replace | keep.
overwrites[].keystringYes
The overwrite's key, as the preview listed it.

Replies

StatusMeaning
200Choices 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
400Invalid 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
401Not authenticated
403User 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)
404No such upload in this organization
409A lease upload that was already imported; confirming it again inserts nothing
GET/tabular/uploads/{id}/export

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).

Replies

StatusMeaning
200The 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.
401Not authenticated (no session and no valid API token)
403User not registered, or access limited to specific buildings (a session or a token narrowed to buildings or areas)
404No such upload in this organization
POST/tabular/uploads/{id}/preview

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).

Request body

application/json, required.

FieldTypeRequiredDescription
correctionslist of objectNo
corrections[].columnstringYes
corrections[].rowintegerYes
corrections[].valuestringYes
date_formatstringNo
mappingslist of objectYes
mappings[].columnstringYes
The file's column header, verbatim.
mappings[].fieldstringNo
Target field key, or null = "ignore this column".

Replies

StatusMeaning
200Transformed samples via the SAME engine the confirmed job runs, plus every vocabulary value that would not resolve (each with ranked candidates)
400The choices do not compose into a valid document
401Not authenticated
403User not registered
404No such upload in this organization
GET/tabular/uploads/{id}/profile

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The upload's id

Replies

StatusMeaning
200The 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
401Not authenticated
403User not registered, or a role that cannot add data
404No such upload in this organization
409The upload was already confirmed; its data is in BrickFlow
POST/tabular/workbook

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
content_base64stringYes
The workbook's bytes, base64 (standard alphabet).
header_rowintegerNo
The Excel row (1 is the first) holding the column headers, as the person chose it. Absent: BrickFlow finds it.
sheetstringNo
The sheet the person chose. Absent: BrickFlow finds it.

Replies

StatusMeaning
200xls) 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
400Not an Excel workbook, no sheet with content, or a sheet or header row that does not exist
401Not authenticated
403User not registered
413The 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

NameInRequiredDescription
monthqueryNostring.
Reporting month (YYYY-MM). Absent, the default, returns every alert the org has, which is the current-state inbox view.
buildingqueryNostring.
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_monthqueryNostring.
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_monthqueryNostring.
Last reading month (YYYY-MM, inclusive): only the alerts whose period is this month or earlier. Absent leaves the end open.
limitqueryNointeger (int32).
A read without it is deprecated: it answers every alert as a bare array and is kept for automation-key clients only.
offsetqueryNointeger (int32).
Alerts to skip before the page, newest first. Only with limit; absent is 0.
kindqueryNostring.
Only the alerts of this kind (missing_period, spike, drop, charge_mismatch, missing_bill, inactive_meter or usage_bill_gap). Only with limit.
statusqueryNostring.
Only the alerts in this status (open, acknowledged, dismissed or healed). Only with limit.
meter_keyqueryNostring.
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.
triagequeryNostring.
tsv. Only with limit.
assignedqueryNostring.
Only the alerts assigned to the caller (me) or to no one (nobody). Only with limit.

Replies

StatusMeaning
200to_month, and only building's when given.
400month, 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
401Not authenticated
403User not registered
GET/anomalies/{id}

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
id

Replies

StatusMeaning
200One 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
401Not authenticated
403User not registered
404No 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

NameInRequiredDescription
idpathYesinteger (int64).
id

Request body

application/json, required.

membership_id: None unassigns.

FieldTypeRequiredDescription
membership_idintegerNo

Replies

StatusMeaning
200Assignment updated
400membership_id does not belong to this org, or its member cannot see the alert's meter
401Not authenticated
403User not registered, or lacks write access
404No such alert for this org
POST/anomalies/{id}/follow-up

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
onstringNo

Replies

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

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (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).

FieldTypeRequiredDescription
actionstringYes
notestringNo
root_causestringNo

Replies

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

Any API token

Parameters

NameInRequiredDescription
from_monthqueryNostring.
First reading month (YYYY-MM, inclusive); absent leaves the start open.
to_monthqueryNostring.
Last reading month (YYYY-MM, inclusive); absent leaves the end open.

Replies

StatusMeaning
200Counts 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
400from_month or to_month given but not a valid YYYY-MM, or from_month after to_month
401Not authenticated
403User not registered
POST/anomaly-mutes

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
muted_kindslist of stringNo
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.
reasonstringNo
series_idintegerYes
untilstringNo
When the mute ends by itself. Absent/omitted = muted until someone removes it; a moment already past answers 400.

Replies

StatusMeaning
200Mute created
400No kind of alert named, or a kind that cannot be muted
401Not authenticated
403User lacks owner/admin role
DELETE/anomaly-mutes/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
id

Replies

StatusMeaning
200Mute removed
401Not authenticated
403User lacks owner/admin role
404No such mute for this org
GET/anomaly-settings

Any API token

Replies

StatusMeaning
200The org's anomaly sensitivity setting and active mutes
401Not authenticated
403User 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".

FieldTypeRequiredDescription
coldstart_modz_thresholdnumberNo
min_prior_same_monthintegerNo
min_reads_for_cadenceintegerNo
min_reads_for_spikeintegerNo
modz_thresholdnumberNo
monthly_gap_max_daysintegerNo
monthly_gap_min_daysintegerNo
presetstringYes
"high" | "medium" | "low" | "custom".

Replies

StatusMeaning
200Setting saved
400Unknown preset
401Not authenticated
403User 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".

FieldTypeRequiredDescription
coldstart_modz_thresholdnumberNo
min_prior_same_monthintegerNo
min_reads_for_cadenceintegerNo
min_reads_for_spikeintegerNo
modz_thresholdnumberNo
monthly_gap_max_daysintegerNo
monthly_gap_min_daysintegerNo
presetstringYes
"high" | "medium" | "low" | "custom".

Replies

StatusMeaning
200Alert counts under the candidate vs. current setting
400Unknown preset
401Not authenticated
403User lacks owner/admin role
PUT/anomaly-settings/usage-bill-gap

Token that can change data

Request body

application/json, required.

1-067).

FieldTypeRequiredDescription
threshold_percentnumberNo
Percent of the bill, 1 to 100; null goes back to the default (10).

Replies

StatusMeaning
200Threshold saved; the whole setting as GET returns it
400The threshold is outside 1 to 100 percent
401Not authenticated
403User lacks owner/admin role
GET/calendar

Any API token

Replies

StatusMeaning
200The 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
401Not authenticated (no session and no valid API token)
403User not registered
POST/calendar/events

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
descriptionstringNo
event_datestringYes
"YYYY-MM-DD".
titlestringYes

Replies

StatusMeaning
200Created
400Blank title, or event_date is not an ISO date
401Not authenticated
403Your 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

NameInRequiredDescription
idpathYesinteger (int64).
calendar_event id

Request body

application/json, required.

FieldTypeRequiredDescription
descriptionstringNo
event_datestringYes
"YYYY-MM-DD".
titlestringYes

Replies

StatusMeaning
200Updated
400Blank title, or event_date is not an ISO date
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings
404No 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

NameInRequiredDescription
idpathYesinteger (int64).
calendar_event id

Replies

StatusMeaning
200Deleted
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings
404No custom event with this id in your organization
GET/calendar/preferences

Token that can change data

Replies

StatusMeaning
200The caller's own calendar choices in the active organization
401Not authenticated
403User not registered
500Reading 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.

FieldTypeRequiredDescription
show_equipmentbooleanYes
Equipment warranty ends and service due dates. On unless the person turned it off.

Replies

StatusMeaning
200Saved; the caller's own calendar choices
401Not authenticated
403User not registered
500Saving the choice failed
GET/notifications/reminder-setting

Token that can change data

Replies

StatusMeaning
200The org's deadline reminder lookahead window, in days
401Not authenticated
403Scoped roles cannot view this org-wide setting
PUT/notifications/reminder-setting

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
reminder_window_daysintegerYes

Replies

StatusMeaning
200Reminder window saved
400reminder_window_days is not a positive number of days
401Not authenticated
403User lacks owner/admin role
POST/notifications/test

Token that can change data

Replies

StatusMeaning
200Test email sent
401Not authenticated
403User not registered
503SMTP is not configured on this server

Targets (26)

GET/projectsLists the organization's projects.

Any API token

Replies

StatusMeaning
200The 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or a member limited to specific buildings holds no Projects grant
500Reading 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

StatusMeaning
200]}: the new projects' ids, in request order
302Redirect to /projects: the list was empty, so no project was created
400Malformed 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or the caller's role cannot modify this organization's data
413The body is over the JSON size limit
500Reading 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

NameInRequiredDescription
idpathYesinteger (int64).
The project's id

Request body

application/json, required.

Body of PUT /api/v1/projects/{id}.sql already comments out).

FieldTypeRequiredDescription
actual_costnumberNo
budgetnumberYes
budget_yearintegerNo
Calendar year, 1900 to 2200. Absent means null.
cost_currencystringNo
Three upper-case letters. Absent or null keeps the stored currency: a project's money never changes currency by omission.
descriptionstringNo
lifetime_yearsintegerNo
Whole years, 1 to 100 (migration 0135). The request is a full replacement: absent means null. Relational only, no graph triple.
mandatorybooleanNo
Absent means false.
measured_savingsnumberNo
namestringYes
percent_completenumberNo
prioritystringYesOne of: high, medium, low, critical.
project_typestringYes
projected_savingsnumberNo
start_dateintegerNo
start_date's INTEGER column range at validation (see types::Project's field note).
statusstringYesOne 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_onstringNo
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_dateintegerYes
target_iristringNo
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

StatusMeaning
200The project was updated
400Malformed 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
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or the caller's role cannot modify this organization's data
404No project with this id in this organization
413The body is over the JSON size limit
500Reading 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

NameInRequiredDescription
idpathYesinteger (int64).
The project's id

Replies

StatusMeaning
200The project and its graph node were deleted; each target it was linked to records the removal in its history
400The graph refused to retract the project's node; the project is kept (JSON EditRefusal body)
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User not registered, or the caller's role cannot modify this organization's data
404No project with this id in this organization
500Reading 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.

FieldTypeRequiredDescription
categorystringYesOne of: Energy, Water, Waste, Ghg, Data, Certification, Custom.
descriptionstringNo
end_datestringNo
namestringYes
offtrack_threshold_pctnumberNo
owner_membership_idintegerNo
reminder_lead_daysnumberNo
5 reach the sentence, not the parser's.
scope_irislist of stringNo
Region, campus, site or building IRIs; empty or absent is the whole organization.
start_datestringYes

Replies

StatusMeaning
200The new program
400The body could not be read, or a value breaks a rule; the body is the sentence
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
500Error saving the program
PUT/target-programs/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
categorystringNoOne of: Energy, Water, Waste, Ghg, Data, Certification, Custom.
descriptionstringNo
end_datestringNo
expected_updated_atstringNo
Required: the updated_at the caller last read (RFC3339).
namestringNo
offtrack_threshold_pctnumberNo
owner_membership_idintegerNo
reasonstringNo
reminder_lead_daysnumberNo
scope_irislist of stringNo
start_datestringNo
statusstringNoOne of: Active, Completed, Archived.

Replies

StatusMeaning
200The program as saved
400The body could not be read, or a value breaks a rule; the body is the sentence
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No program with this id in your organization
409The program is not active, somebody else saved it first, or it holds targets so its category cannot change
500Error saving the program
DELETE/target-programs/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target_program id

Replies

StatusMeaning
200Deleted
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Only owners and admins can delete a program, your role cannot modify this organization's data, or User is not registered
404No program with this id in your organization
409This program has targets or recorded changes, so it cannot be deleted; archive it instead
500Error saving the program
GET/target-programs/{id}/revisions

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
program id

Replies

StatusMeaning
200The program's recorded changes, newest first; they outlive a deleted program
401Not authenticated (no session and no valid API token)
402subscription_inactive
403User 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.
404No program with this id in your organization
500Error reading targets
GET/targets

Any API token

Replies

StatusMeaning
200Every program and target of the organization, with live progress for the active ones
401Not signed in
402subscription_inactive
403User is not registered, or your access is limited to specific buildings (ask an owner or admin for access)
500Error reading targets
POST/targets

Token that can change data

Request body

application/json, required.

FieldTypeRequiredDescription
area_unitstringNoOne of: Ft2, M2.
baseline_startstringNo
baseline_valuenumberNo
baseline_value_reasonstringNo
cert_levelstringNo
cert_schemestringNoOne of: Leed, BomaBest, EnergyStar, Well, Fitwel, ZeroCarbonBuilding, Other.
cert_scheme_otherstringNo
directionstringYesOne of: Reduce, Increase.
formstringYesOne of: Absolute, Intensity, PercentChange, YesNo.
frequencystringYesOne of: Monthly, Quarterly, Annual.
ghg_measurestringNoOne of: Scope1, Scope2Location, Scope12, Scope3Cat1, Scope3Cat6, Scope3Cat7, Scope3Cat8, Scope3Cat13.
notesstringNo
program_idintegerYes
responsible_membership_idintegerNo
start_datestringYes
subject_iristringNo
null or absent is the organization; a Portfolio IRI is stored as the organization.
surveyobjectNo
survey.group_idintegerYes
survey.question_idstringYes
target_datestringYes
target_typestringYesOne of: Ghg, SiteEui, EnergyStarScore, Certification, Custom, DataCoverage, DataQuality.
target_valuenumberNo
titlestringYes
unitstringNo
A custom target's unit; every other type's is set by the server.

Replies

StatusMeaning
200The new target, with its progress
400The body could not be read, or a value breaks a rule; the body is the sentence
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No program with this id in your organization
409The program is archived or completed, so it and its targets are read-only
500Error saving the target
GET/targets/{id}

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Replies

StatusMeaning
200The target with its progress, chart points, baseline, buildings and provenance
401Not signed in
402subscription_inactive
403User is not registered, or your access is limited to specific buildings (ask an owner or admin for access)
404No target with this id in your organization
500Error reading targets
PUT/targets/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Request body

application/json, required.

The type, measure, form and subject are accepted only to be refused when they differ.

FieldTypeRequiredDescription
area_unitstringNoOne of: Ft2, M2.
baseline_startstringNo
baseline_valuenumberNo
baseline_value_reasonstringNo
cert_levelstringNo
cert_schemestringNoOne of: Leed, BomaBest, EnergyStar, Well, Fitwel, ZeroCarbonBuilding, Other.
cert_scheme_otherstringNo
directionstringNoOne of: Reduce, Increase.
expected_updated_atstringNo
Required: the updated_at the caller last read (RFC3339).
formstringNoOne of: Absolute, Intensity, PercentChange, YesNo.
frequencystringNoOne of: Monthly, Quarterly, Annual.
ghg_measurestringNoOne of: Scope1, Scope2Location, Scope12, Scope3Cat1, Scope3Cat6, Scope3Cat7, Scope3Cat8, Scope3Cat13.
notesstringNo
reasonstringNo
Required (1 to 500 characters) when a baseline, a target value, a date, the direction or the area unit changes.
responsible_membership_idintegerNo
start_datestringNo
subject_iristringNo
surveyobjectNo
survey.group_idintegerYes
survey.question_idstringYes
target_datestringNo
target_typestringNoOne of: Ghg, SiteEui, EnergyStarScore, Certification, Custom, DataCoverage, DataQuality.
target_valuenumberNo
titlestringNo
unitstringNo
Accepted only to be refused when it differs: a custom target's unit never changes.

Replies

StatusMeaning
200The target as saved, with its progress
400The body could not be read, or a value breaks a rule; the body is the sentence
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization
409The 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
500Error saving the target
DELETE/targets/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Replies

StatusMeaning
200Deleted
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Only owners and admins can delete a target, your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization
409The program is read-only, or this target has recorded changes so it cannot be deleted; archive it instead
500Error saving the target
POST/targets/{id}/archive

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Request body

application/json, required.

FieldTypeRequiredDescription
reasonstringNo

Replies

StatusMeaning
200The archived target (progress is null, progress_reason is archived)
400The body could not be read, or the reason is over 500 characters
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization
409The program is read-only, or this target is already archived
500Error saving the target
PUT/targets/{id}/gresb

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
net_zerobooleanYes
The target is a net zero target.
publicly_communicatedbooleanYes
The target has been published outside the organization.
science_basedbooleanYes
5 C science-based pathway, for example validated by SBTi.

Replies

StatusMeaning
200The answers as saved (the current ones when nothing changed)
400The body could not be read, or one of the three answers is missing
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization
409The program is read-only, or the target is archived
500Error saving the GRESB answers
GET/targets/{id}/initiatives

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Replies

StatusMeaning
200The projects linked to the target with their impact in the target's unit, how each counts, and the totals of what counts
401Not signed in
402The organization's subscription has ended (subscription_inactive)
403User is not registered, or your access is limited to specific buildings (ask an owner or admin for access)
404No target with this id in your organization
500Error reading initiatives
PUT/targets/{id}/initiatives/{project_id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id
project_idpathYesinteger (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.

FieldTypeRequiredDescription
expected_impactnumberNo
measured_impactnumberNo

Replies

StatusMeaning
200The link as it now stands. A PUT that changes nothing writes no revision and answers the same way
400The body could not be read, has an unknown field, or an impact is negative or not a number
401Not signed in, or only an API token (tokens never write)
402The organization's subscription has ended (subscription_inactive)
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization, or No project with this id in your organization
409The program is read-only, or This target is archived, so it is read-only.
500Error saving the initiative
DELETE/targets/{id}/initiatives/{project_id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id
project_idpathYesinteger (int32).
project id

Replies

StatusMeaning
200The link is removed and the change recorded
401Not signed in, or only an API token (tokens never write)
402The organization's subscription has ended (subscription_inactive)
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization, or This project is not linked to this target.
409The program is read-only, or This target is archived, so it is read-only.
500Error saving the initiative
GET/targets/{id}/progress-entries

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Replies

StatusMeaning
200The target's typed figures, ascending by period; empty for a target that takes no figures
401Not signed in
402subscription_inactive
403User is not registered, or your access is limited to specific buildings (ask an owner or admin for access)
404No target with this id in your organization
500Error reading targets
POST/targets/{id}/progress-entries

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Request body

application/json, required.

FieldTypeRequiredDescription
notestringNo
period_startstringYes
The first day of the month, quarter or year the figure covers.
valuenumberYes
At or above 0; 1 or 0 for a yes or no target.

Replies

StatusMeaning
200The target's figures and the target with its progress; the target's updated_at is unchanged
400The body could not be read, or the period, value or note breaks a rule; the body is the sentence
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization
409The program or target is read-only, the target's progress is not typed, or there is already a figure for this period
500Error saving the figure
PUT/targets/{id}/progress-entries/{entry_id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id
entry_idpathYesinteger (int64).
figure id

Request body

application/json, required.

FieldTypeRequiredDescription
expected_updated_atstringNo
Required: the figure's updated_at as last read (RFC3339).
notestringNo
Absent leaves the note alone; null or blank clears it.
reasonstringNo
Required (1 to 500 characters).
valuenumberNo

Replies

StatusMeaning
200The target's figures and the target with its progress; a correction that changes nothing records nothing
400The 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
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization, or No progress figure with this id on this target
409The program or target is read-only, the target's progress is not typed, or somebody else changed this figure first
500Error saving the figure
DELETE/targets/{id}/progress-entries/{entry_id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id
entry_idpathYesinteger (int64).
figure id

Request body

application/json, required.

FieldTypeRequiredDescription
expected_updated_atstringNo
Required: the figure's updated_at as last read (RFC3339).
reasonstringNo
Required (1 to 500 characters).

Replies

StatusMeaning
200The target's remaining figures and the target with its progress; the deletion and its reason stay in history
400The body could not be read, or the reason or expected_updated_at is missing; the body is the sentence
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No target with this id in your organization, or No progress figure with this id on this target
409The program or target is read-only, the target's progress is not typed, or somebody else changed this figure first
500Error saving the figure
GET/targets/{id}/revisions

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
target id

Replies

StatusMeaning
200The target's recorded changes, newest first; they outlive a deleted target
401Not authenticated (no session and no valid API token)
402subscription_inactive
403User 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.
404No target with this id in your organization
500Error 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.

FieldTypeRequiredDescription
baseline_startstringNo
building_iristringYes
frequencystringYesOne of: Monthly, Quarterly, Annual.
notesstringNo
program_idintegerYes
responsible_membership_idintegerNo
start_datestringYes
target_datestringYes
titlestringNo

Replies

StatusMeaning
200The new target, copied from the building's ENERGY STAR target, with its progress
400The 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
401Not signed in, or only an API token (tokens never write)
402subscription_inactive
403Your role cannot modify this organization's data, or User is not registered
404No program with this id in your organization
409The program is archived or completed, so it and its targets are read-only, or ENERGY STAR has two values for this building's target
422ENERGY STAR's target is a percent better than the national median, or the baseline period must be confirmed
500Error saving the target
GET/targets/gresb

Any API token, also Read reports only

Replies

StatusMeaning
200The GRESB answers of every target that has any; a target missing here has all three answers no
401Not signed in
402subscription_inactive
403User is not registered, or your access is limited to specific buildings (ask an owner or admin for access)
500Error reading the GRESB answers
GET/targets/summary

Any API token, also Read reports only

Replies

StatusMeaning
200How many active targets are on track, off track, incomplete or achieved
401Not signed in
402subscription_inactive
403User is not registered, or your access is limited to specific buildings (ask an owner or admin for access)
500Error reading targets

ENERGY STAR Portfolio Manager (6)

GET/espm-project-reviews

Token that can change data

Replies

StatusMeaning
200The choices an ENERGY STAR re-import waits for, oldest first
401Not authenticated
403The caller's access is limited to specific buildings
500The choices could not be read
POST/espm-project-reviews/{id}/resolve

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The review's number

Request body

application/json, required.

FieldTypeRequiredDescription
choicestringYes
link, keep_both, keep_mine or take_theirs.

Replies

StatusMeaning
200The choice was applied; the review is kept as a record
400The choice is not one of those offered for this review
401Not authenticated
403The caller's role cannot change this organization's data
404No open choice with that number in this organization
409Another project here already holds that ENERGY STAR project
500The choice could not be saved, or the project's graph copy did not update
GET/espm-projects

Any API token

Replies

StatusMeaning
200ENERGY STAR-tracked improvement projects, org-wide
401Not authenticated
403Caller holds no Domain::Projects grant at all
500The 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

StatusMeaning
200Every ENERGY STAR Portfolio Manager scheduled-sync enrollment in the caller's org
401Not authenticated
403Only 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

NameInRequiredDescription
property_idsqueryYesstring.
Comma-separated ENERGY STAR Portfolio Manager property ids, up to [PROPERTY_IDS_MAX].

Replies

StatusMeaning
200The BrickFlow building IRI each named property maps to, same order as the request
400property_ids empty, non-numeric, or names more than the per-request limit
401Not authenticated
403User not registered
POST/espm/sync

Token that can change data

Replies

StatusMeaning
200ENERGY 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
400No connected ENERGY STAR Portfolio Manager account for this organization
401Not authenticated
403User not registered
503ENERGY 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

StatusMeaning
200The notify address is reachable. Empty body.
POST/green-button/notification

Token that can change data

Request body

application/atom+xml, required. string

Replies

StatusMeaning
200Notification 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.
400Body is not a well-formed BatchList
404None 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.
429Rate limit exceeded
GET/green-button/providers`GET /api/v1/green-button/providers`: registry listing.sql`, let alone echoed here.

Any API token

Replies

StatusMeaning
200Registered utility providers (public fields only)
401Not authenticated
403User not registered
500Database 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

NameInRequiredDescription
idpathYesstring.
sync_id from POST /api/v1/green-button/sync/{slug}

Replies

StatusMeaning
200running, or done with the status and body the sync ended with
401Not authenticated
403User not registered
404No 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

NameInRequiredDescription
slugpathYesstring.
slug
subscription_idqueryNostring.
Sync only this account (ESPI subscription id) instead of every account of the utility
waitqueryNoboolean.
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

StatusMeaning
202The 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
401Not authenticated
403User not registered
404Unknown provider, or no stored authorization for this org/provider
500Missing 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

StatusMeaning
200DMD 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
401Not authenticated
403User not registered
413Payload too large
429The caller has uploaded GK_UPLOAD_PER_MINUTE_LIMIT files in the last minute; plain text saying when to upload the rest, with Retry-After
500Ingest 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

StatusMeaning
200Roadmap items, most-upvoted first
401Not authenticated
403User 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.

FieldTypeRequiredDescription
descriptionstringNo
namestringYes

Replies

StatusMeaning
200Suggestion recorded (or merged onto an existing same-name item)
400Empty name
401Not authenticated
403User not registered
500Database 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

NameInRequiredDescription
idpathYesinteger (int64).

Replies

StatusMeaning
200Upvote recorded (idempotent)
401Not authenticated
403User not registered
404No such connector request in this org
500Database 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

NameInRequiredDescription
idpathYesinteger (int64).

Replies

StatusMeaning
200Upvote retracted (idempotent)
401Not authenticated
403User not registered
404No such connector request in this org
500Database 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

StatusMeaning
200Entities other organizations have shared with this one
401Not authenticated
403Your 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants
fromqueryNointeger (int64).
Inclusive lower bound on end_date.
toqueryNointeger (int64).
Exclusive upper bound on start_date.
limitqueryNointeger (int64).
Bills per page: 200 when absent, at most 500 (a larger value is read as 500), at least 1.
offsetqueryNointeger (int64).
Bills to skip, newest first: 0 when absent, never negative.

Replies

StatusMeaning
200One 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
400limit is below 1 ("limit must be 1 or more") or offset is negative ("offset must be 0 or more")
401Not authenticated
403Your access is limited to specific buildings, this grant does not cover financial, or the building's bills were shared without energy
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200The shared building's summary, read from the granting org's graph
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover topology
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200The connectors that fed the shared building, from the granting org's graph
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover data sources
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200Twelve 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
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover energy
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200The shared entity's equipment, from the granting org's graph
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover equipment
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200Leases inside the shared building, from the granting org; no tenant organization id, link flag or linked organization name
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover leases
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200The shared entity's meters, from the granting org's graph; empty when the grant excludes meters
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover energy
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200Projects targeted inside the shared building, from the granting org
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover projects
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants
series_idsqueryNostring.
id values, as the building's meters list them (series_id), up to 200.
startqueryNostring (date-time).
Inclusive lower bound, RFC 3339.
endqueryNostring (date-time).
Exclusive upper bound, RFC 3339.

Replies

StatusMeaning
200Readings of the requested meters that sit in the shared building, from the granting org; ids outside it are absent
400series_ids is missing, malformed, empty or names more than 200 ids
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover energy
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200The shared entity with its space tree, from the granting org's graph
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover topology
404No such grant shared with this organization
500The 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

NameInRequiredDescription
idpathYesinteger (int64).
The org_grant id from GET /api/v1/external-grants

Replies

StatusMeaning
200The shared building's sustainability facts, from the granting org
401Not authenticated
403Your access is limited to specific buildings, or this grant does not cover sustainability
404No such grant shared with this organization
500The shared scope, the reported metrics, the target or the certifications could not be read
GET/ingest/connectors

Any API token

Replies

StatusMeaning
200Registered connector descriptors
401Not authenticated
GET/ingest/connectors/buildings

Any API token

Replies

StatusMeaning
200Buildings 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.
401Not authenticated
403User not registered
GET/ingest/jobs

Any API token

Parameters

NameInRequiredDescription
recentqueryNointeger (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).
connectorqueryNostring.
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

StatusMeaning
200Ingest 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
401Not authenticated
403User not registered
POST/ingest/jobs

Token that can change data

Parameters

NameInRequiredDescription
Idempotency-KeyheaderNostring.
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.

FieldTypeRequiredDescription
anchor_iristringNo
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_idstringYes
Registered connector id (see GET /api/v1/ingest/connectors).
encodingstringNoOne of: text, base64.
How payload is encoded in a job submission.
filenamestringNo
payloadstringYes
The payload, as text or base64 per encoding.

Replies

StatusMeaning
200Job 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
400Unknown connector or undecodable payload
401Not authenticated
403User not registered, or limited to some buildings: a file import is refused to them
409A 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)
422The Idempotency-Key was already used for a different upload; nothing was written
GET/ingest/jobs/{id}

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Ingest job id

Replies

StatusMeaning
200Job detail incl. raw_ref and provenance IRI; for an organization-wide role also periods_already_filled (up to 50) and readings_set_aside (all)
401Not authenticated
403User not registered
404No 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

NameInRequiredDescription
idpathYesinteger (int64).
Ingest job id

Replies

StatusMeaning
200Job re-run to completion (status committed or failed again), with periods_already_filled (up to 50) and readings_set_aside (all)
400The job is not in a retryable (failed) state
401Not authenticated
403User not registered, or lacks write access
404No such job in this org
409A 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

NameInRequiredDescription
job_idpathYesinteger (int64).
The upload's ingest job id

Request body

application/json, required.

Body of POST /api/v1/ingest/jobs/{job_id}/reading-conflicts/resolve.

FieldTypeRequiredDescription
choicestringYes
replace makes every value the upload is waiting on the saved reading; keep keeps every saved one.

Replies

StatusMeaning
200Settled: decided periods are took_proposed or kept_recorded, left_open stay open (each can be chosen on its own)
400An unknown choice ("choice must be \"replace\" or \"keep\""); nothing changed
401Not authenticated
402The organization's subscription has ended (subscription_inactive)
403User 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
404No such upload in this organization
409The 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
500Saving 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

NameInRequiredDescription
tokenqueryNostring.
The token from the email's link.

Replies

StatusMeaning
200A page asking to confirm stopping setup emails (HTML; no sign-in needed)
400The token is missing, cut short or not BrickFlow's (HTML page saying so)
503The server cannot check tokens yet (HTML page saying so)
POST/setup-emails/unsubscribe

Token that can change data

Parameters

NameInRequiredDescription
tokenqueryNostring.
The token from the email's link.

Replies

StatusMeaning
200Setup emails stopped for this person and organization (HTML page saying so; also the RFC 8058 one-click target)
400The token is missing, cut short or not BrickFlow's (HTML page saying so)
500The choice could not be saved (HTML page saying so)
503The 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

StatusMeaning
200Verified and recorded: the email was accepted (its files are imported in the background), held for approval, already received, or for no organization's address
400Body too large, or signed but not an event BrickFlow can read
401Unsigned, a signature that does not match, or signed more than five minutes from now
409This delivery was already received (a replay); nothing was done
500Verified but recording failed; the mail service may send it again
503Emailing bills in is not switched on or not fully set up on this server

Documents (10)

GET/documents

Any API token

Parameters

NameInRequiredDescription
limitqueryNointeger (int64).
The newest this many documents the caller can see, 1 to 2000. Opt-in: without it every one comes back, as before.

Replies

StatusMeaning
200Uploaded 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
400limit is not a whole number or not between 1 and 2000 ("limit must be between 1 and 2000")
401Not authenticated
403User not registered
POST/documents

Token that can change data

Parameters

NameInRequiredDescription
Idempotency-KeyheaderNostring.
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.

FieldTypeRequiredDescription
anchor_iristringNo
The granted building/space this upload attaches to.
document_typestringYes
filenamestringNo
Original filename, recorded as the ingest job's source_detail.
payloadstringYes
Base64-encoded file bytes.
upload_batch_idstringNo
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

StatusMeaning
200Uploaded and staged for extraction (status=pending)
400Unregistered document_type, undecodable base64, an unsupported file type (not a PDF/PNG/JPEG), or (scoped roles only) a missing anchor_iri
401Not authenticated
403User not registered, or (scoped roles only) anchor_iri is outside the caller's granted write scope
429The 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
500Ingest or database error
GET/documents/{id}

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Document extraction id

Replies

StatusMeaning
200Extraction 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
401Not authenticated
403User not registered
404No 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

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
allow_duplicatebooleanNo
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_datedbooleanNo
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.
buildingslist of objectNo
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_iristringYes
A building in this organization's graph.
buildings[].record_idxintegerYes
One of the records being confirmed.
correctionslist of objectNo
corrections[].field_keystringYes
corrections[].record_idxintegerYes
Usually an EXISTING record from the extraction.
corrections[].valuestringYes
The corrected value.
manual_entrybooleanNo
finish THIS upload by hand, in place, because no extraction engine is configured (pending) or extraction failed (failed).
replacebooleanNo
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_minutesintegerNo
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

StatusMeaning
200Confirmed: 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
400A 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
401Not authenticated
403User not registered, or a scoped role (contractor/tenant), unchanged for manual_entry confirmations
404No such document in this org
409A 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)
500Ingest or database error
GET/documents/{id}/file

Any API token

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
Document extraction id

Replies

StatusMeaning
200The original uploaded bytes, with the sniffed content type and an inline Content-Disposition naming the uploaded file (cleaned)
401Not authenticated
403User not registered
404No 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

NameInRequiredDescription
idpathYesinteger (int64).
Document extraction id

Replies

StatusMeaning
200A new extraction attempt was started
401Not authenticated
403User lacks write access, or is a scoped role
404No such document in this org
409Document 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
429The 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
500Database error
503No 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

StatusMeaning
2001's >=95% extraction-accuracy target
401Not authenticated
403User 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

StatusMeaning
200Recent multi-file upload batches with per-status counts
401Not authenticated
403User not registered
POST/documents/retry-failed

Token that can change data

Request body

application/json, required.

Body of POST /api/v1/documents/retry-failed.

FieldTypeRequiredDescription
upload_batch_idstringYes
The batch, as GET /api/v1/documents/batches names it.

Replies

StatusMeaning
200Every 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
400upload_batch_id is not 1-64 characters
401Not authenticated
403User lacks write access, or is a scoped role
404No upload batch with this id in this org
429Reading 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
500Database error
503No 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

StatusMeaning
200The caller's own DataSources-write grants, labeled, empty for org-wide roles, whose uploads never anchor
401Not authenticated
403User not registered

Leases (4)

GET/leases

Any API token

Parameters

NameInRequiredDescription
buildingqueryNostring.
Only this building's leases (full IRI, URL-encoded).

Replies

StatusMeaning
200Every 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)
401Not authenticated (no session and no valid API token)
403building= the answer is an empty list)
500Error 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.

FieldTypeRequiredDescription
building_iristringYes
A building of this organization (full IRI).
end_datestringNo
YYYY-MM-DD, on or after start_date; omit or null for open-ended.
lease_typestringYes
One of gross, net, modified_gross, triple_net, other.
space_iristringNo
A floor, room or space inside building_iri; omit or null for the whole building.
start_datestringYes
YYYY-MM-DD.
tenant_namestringYes
tenant_org_idintegerNo
Optional link to the tenant's BrickFlow organization (a positive 32-bit integer). An id no organization holds stores no link.

Replies

StatusMeaning
200Created
400Blank 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
401Not authenticated
403Your role cannot modify leases, or the lease's space (else building) is outside your granted Leases write scope
500Error reading the graph or writing the lease
PUT/leases/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
building_iristringYes
A building of this organization (full IRI).
end_datestringNo
YYYY-MM-DD, on or after start_date; omit or null for open-ended.
lease_typestringYes
One of gross, net, modified_gross, triple_net, other.
space_iristringNo
A floor, room or space inside building_iri; omit or null for the whole building.
start_datestringYes
YYYY-MM-DD.
tenant_namestringYes
tenant_org_idintegerNo
Optional link to the tenant's BrickFlow organization (a positive 32-bit integer). An id no organization holds stores no link.

Replies

StatusMeaning
200Updated
400Same validation as POST
401Not authenticated
403Your role cannot modify leases, or either the stored lease's or the new target (space, else building) is outside your granted Leases write scope
404No lease with this id in your organization
500Error reading the graph or writing the lease
DELETE/leases/{id}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
lease id

Replies

StatusMeaning
200Deleted
401Not authenticated
403Your role cannot modify leases, or the stored lease's space (else building) is outside your granted Leases write scope
404No lease with this id in your organization
500Error reading the graph or deleting the lease

Surveys and custom records (16)

GET/record-types

Any API token

Replies

StatusMeaning
200The record types defined by shape files in ontology/shapes that the caller may read, with their fields
401Not authenticated (no session and no valid API token)
GET/records/{type}

Any API token

Parameters

NameInRequiredDescription
typepathYesstring.
the record type's name, from /api/v1/record-types

Replies

StatusMeaning
200Every record of the type in the caller's organization: BrickFlow ID, field values and each source's own IDs
401Not authenticated
403A scoped caller (limited to specific buildings) and the type's shape does not say gk:scopedRead
404No such record type
500The records could not be read
POST/records/{type}

Token that can change data

Parameters

NameInRequiredDescription
typepathYesstring.
the record type's name

Request body

application/json, required.

FieldTypeRequiredDescription
valuesobjectYes
Field key to value; blank removes the value.

Replies

StatusMeaning
200Created, with its new BrickFlow ID
400The values break the shape's rules: the body lists each problem and how to fix it
401Not authenticated
403Your role cannot modify this organization's data, or it is limited to specific buildings
404No such record type
500The record could not be saved or checked
GET/records/{type}/{id}

Any API token

Parameters

NameInRequiredDescription
typepathYesstring.
the record type's name
idpathYesstring.
the BrickFlow ID, BF-XXXXX-XXXXX

Replies

StatusMeaning
200The record with its field values and each source's own IDs
401Not authenticated
403A scoped caller and the type's shape does not say gk:scopedRead
404No such record type, or no record with this BrickFlow ID in your organization
500The record could not be read
PUT/records/{type}/{id}

Token that can change data

Parameters

NameInRequiredDescription
typepathYesstring.
the record type's name
idpathYesstring.
the BrickFlow ID, BF-XXXXX-XXXXX

Request body

application/json, required.

FieldTypeRequiredDescription
valuesobjectYes
Field key to value; blank removes the value.

Replies

StatusMeaning
200Updated: the values sent replace the record's values
400The values break the shape's rules: the body lists each problem and how to fix it
401Not authenticated
403Your role cannot modify this organization's data, or it is limited to specific buildings
404No such record type, or no record with this BrickFlow ID in your organization
500The record could not be saved or checked
GET/records/{type}/checks

Any API token

Parameters

NameInRequiredDescription
typepathYesstring.
the record type's name

Replies

StatusMeaning
200The records that break the shape's rules, each with what is wrong; an empty list means every record passed
401Not authenticated
403A scoped caller and the type's shape does not say gk:scopedRead
404No such record type
500The 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

NameInRequiredDescription
typepathYesstring.
the record type's name

Replies

StatusMeaning
200CSV: BrickFlow ID, every field, then one column per source ID scheme. Never internal addresses or row ids
401Not authenticated
403A scoped caller and the type's shape does not say gk:scopedRead
404No such record type
500The records could not be read
POST/records/{type}/import

Token that can change data

Parameters

NameInRequiredDescription
typepathYesstring.
the record type's name
sourcequeryNostring.
a name for the file's origin, kept beside each Source ID
Idempotency-KeyheaderNostring.
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

StatusMeaning
200How many rows were created and updated, which rows need a person to confirm a match first, and which rows broke the shape
400The file itself cannot be imported (no header, an unknown column, unreadable CSV); nothing was changed
401Not authenticated
403Your role cannot modify this organization's data, or it is limited to specific buildings
404No such record type
413The file is over 5 MB
500The records could not be saved or checked
GET/schemasAll form schemas plus the derived document-type registry, in one fetch.

Any API token

Replies

StatusMeaning
200Every form schema reduced from ontology/shapes and ontology/forms, plus the registered extraction document types. Identical for every caller; ETag'd by content
304Not modified (If-None-Match matched)
401Not authenticated
403User not registered
GET/surveys

Any API token

Replies

StatusMeaning
200Every live questionnaire this organization has authored, and every response to any of them (archived questionnaires' responses included)
401Not authenticated
403Your 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.

FieldTypeRequiredDescription
cadencestringYes
descriptionstringNo
expected_updated_atstringNo
RFC3339, from the group's own updated_at. Required on PUT (a 400 without it); ignored on POST, which has nothing to collide with.
namestringYes
place_iristringNo
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.
questionsanyYes
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

StatusMeaning
200Created
400Blank name, unknown cadence, or a question BrickFlow cannot show (the body names it)
401Not authenticated
403Your 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

NameInRequiredDescription
idpathYesinteger (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.

FieldTypeRequiredDescription
cadencestringYes
descriptionstringNo
expected_updated_atstringNo
RFC3339, from the group's own updated_at. Required on PUT (a 400 without it); ignored on POST, which has nothing to collide with.
namestringYes
place_iristringNo
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.
questionsanyYes
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

StatusMeaning
200Saved
400Blank name, unknown cadence, a question BrickFlow cannot show, or a missing/unparseable expected_updated_at
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access
404No live questionnaire with this id in your organization
409Somebody 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

NameInRequiredDescription
idpathYesinteger (int64).
survey_group id

Replies

StatusMeaning
200Retired. Nothing is deleted: the questionnaire leaves the page and every answer given to it stays, exportable
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access
404No live questionnaire with this id in your organization
PATCH/surveys/groups/{id}/responses/{period}

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
survey_group id
periodpathYesstring.
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.

FieldTypeRequiredDescription
removelist of stringNo
The question ids to clear. Absent is empty, clearing nothing is the ordinary case, so it is not a client bug worth surfacing.
setanyNo
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

StatusMeaning
200The period's sheet as it now stands, with this patch merged in
400A 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)
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access
404No live questionnaire with this id in your organization
409This 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

NameInRequiredDescription
idpathYesinteger (int64).
survey_group id
periodpathYesstring.
The period label whose sheet is being reopened

Replies

StatusMeaning
200A draft again, editable; what it looked like before is in the audit log
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access
404No 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

NameInRequiredDescription
idpathYesinteger (int64).
survey_group id
periodpathYesstring.
The period label whose sheet is being submitted

Request body

application/json, required.

POST /groups/{id}/responses/{period}/submit.

FieldTypeRequiredDescription
expected_updated_atstringNo
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

StatusMeaning
200Submitted, carrying the questions it was answering
400A 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)
401Not authenticated
403Your role cannot modify this organization's data, or your access is limited to specific buildings. Ask an owner or admin for access
404No questionnaire with this id in your organization, or nothing answered for this period yet
409Already 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

StatusMeaning
200The release this server is running; a field the build did not record is null
401Not authenticated, or an invalid, revoked or expired API token
402The organization's subscription has ended
403User not registered
500The caller could not be resolved
GET/vocabThe effective vocabulary (seed tier), one fetch per session.

Any API token

Replies

StatusMeaning
200Commodity 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)
304Not modified (If-None-Match matched)
401Not authenticated
403User not registered
GET/vocab/questions

Any API token

Replies

StatusMeaning
200The org's open vocabulary questions, each with ranked candidates from the deterministic proposal engine
401Not authenticated
403User not registered, or a scoped role
POST/vocab/questions/{id}/answer

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).

Request body

application/json, required.

FieldTypeRequiredDescription
canonical_termstringYes
The canonical concept IRI the human confirmed.

Replies

StatusMeaning
200Decision 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)
400Unknown concept IRI
401Not authenticated
403User lacks owner/admin role
404No such open question in this organization
409A 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

StatusMeaning
200Every optional feature and whether this deployment has it configured. Variable names only, never values
401Not authenticated
403Not an owner or admin of the active organization
500The utility provider registry could not be read

Pilot invite (1)

GET/pilot-invite/{token}

Token that can change data

Parameters

NameInRequiredDescription
tokenpathYesstring.
The token from the emailed link

Replies

StatusMeaning
200The answers the setup wizard pre-fills
404The link is unknown, expired or already used

Staff (7)

GET/staff/feedback

Token that can change data

Parameters

NameInRequiredDescription
statusqueryNostring.
open (the default), ready_for_review, fixed, wont_fix or all.

Replies

StatusMeaning
200Up to 500 notes, newest first, without their pictures
400An unknown status filter: use open, ready_for_review, fixed, wont_fix or all
401Not authenticated
403Not BrickFlow staff (or staff access is not configured)
500The notes could not be read
GET/staff/feedback/{id}/screenshot

Token that can change data

Parameters

NameInRequiredDescription
idpathYesinteger (int64).
The note's id

Replies

StatusMeaning
200The PNG of the element
401Not authenticated
403Not BrickFlow staff (or staff access is not configured)
404No such note, or it was saved without a picture
500The picture could not be read
GET/staff/feedback/export

Token that can change data

Parameters

NameInRequiredDescription
statusqueryNostring.
open (the default), ready_for_review, fixed, wont_fix or all.

Replies

StatusMeaning
200Notes 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
400An unknown status filter: use open, ready_for_review, fixed, wont_fix or all
401Not authenticated
403Not BrickFlow staff (or staff access is not configured)
500The 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.

FieldTypeRequiredDescription
bodystringYes
The policy text; not empty.
kindstringYes
privacy or security.
urlstringYes
ca address of this version; must start with https://.
version_datestringYes
YYYY-MM-DD; not later than today (UTC).

Replies

StatusMeaning
201The version is stored. current says whether it is now the newest of its kind
400Unknown 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
401Not authenticated
403Not BrickFlow staff (or staff access is not configured)
409That kind already has a version with that date. Versions are never edited: publish the correction under a new version date
500The 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

NameInRequiredDescription
monthqueryNostring.
YYYY-MM; this month when left out.

Replies

StatusMeaning
200The month's global figure per Google service with the estimated spend, and each organization's counted calls
400month is not YYYY-MM
401Not authenticated
403Not BrickFlow staff (or staff access is not configured)
500The 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.

FieldTypeRequiredDescription
buildingslist of stringNo
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.
emailstringYes
com.
labelstringNo
g. "invite rehearsal". At most 60 characters.
organization_idintegerYes
A test organization (its is_test_organization flag is set).
own_organizationbooleanNo
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_onboardingbooleanNo
Clear the member's setup answers (persona, goals, the onboarded mark) so their next sign-in starts at the first-run screens again.
rolestringYes
One of owner, admin, editor, viewer, limited_editor, limited_viewer, contractor, tenant.
sample_green_button_accountbooleanNo
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_minutesintegerNo
How long the key lives: 5 to 240 minutes, default 60.

Replies

StatusMeaning
200The test member exists with the requested role and a new short-lived automation key; every earlier key of the member is revoked
400The body is not valid, the role is unknown, or the address is not a test mail address
401Not authenticated
403Not BrickFlow staff, or the organization is not marked as a test organization (including one that does not exist)
404No such organization
409A real account already holds that address
500The 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

NameInRequiredDescription
daysqueryNointeger (int64).
Inactive for at least this many days.=3650

Replies

StatusMeaning
200Users 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.
400days is not a whole number
401Not authenticated
403Not BrickFlow staff (or staff access is not configured)
500The list could not be read