Temporal

Base URL: $BUSINESS_API

The object

idstring · optional
subject_idstring · optional
value_idstring · optional
valid_fromstring (date-time) · optional
valid_tostring (date-time) · optional · nullable
system_created_atstring (date-time) · optional
system_superseded_atstring (date-time) · optional · nullable
superseded_by_user_idstring · optional
created_by_user_idstring · optional
reasonstring · optional
The object
{
  "id": "tem_2lr6OdduwHv6ur9ASrXCMZhicRB",
  "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
  "value_id": "val_27HwIF9YGDzAGrHgifrgIDHAGbX",
  "valid_from": "2026-11-19T09:30:00Z",
  "valid_to": "2026-11-19T09:30:00Z",
  "system_created_at": "2026-11-19T09:30:00Z",
  "system_superseded_at": "2026-11-19T09:30:00Z",
  "superseded_by_user_id": "sup_2EmtFmI3zoylR4ArLSeZJKuFl8g",
  "created_by_user_id": "cre_28qxRmKvFI8JVaS3nUY95qcpzIi",
  "reason": "Leitura confirmada no local."
}

The meter bound to a connection at a valid and system time

Logs

GET /temporal/meter-binding

Answers which meter was bound to a connection at as_of_valid_time, as the system recorded it at as_of_system_time; both are RFC 3339 timestamps and default to now. Querying an earlier system time reproduces the answer given before a later correction. Returns 404 when no binding is valid at that moment and 400 for a missing connection_id or a malformed time; requires temporal:read.

Parameters

connection_idstring · query · required

ID of the connection whose meter binding is looked up; required.

as_of_valid_timestring (date-time) · query · optional

Defaults to now

as_of_system_timestring (date-time) · query · optional

Defaults to now

Returns

200 Binding

Show attributes
idstring · optional
subject_idstring · optional
value_idstring · optional
valid_fromstring (date-time) · optional
valid_tostring (date-time) · optional · nullable
system_created_atstring (date-time) · optional
system_superseded_atstring (date-time) · optional · nullable
superseded_by_user_idstring · optional
created_by_user_idstring · optional
reasonstring · optional

Errors 400 · 403 · 404

Permissions temporal:read · Roles: admin, analyst, operations, owner, viewer

curl -X GET "$BUSINESS_API/temporal/meter-binding" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "tem_2lr6OdduwHv6ur9ASrXCMZhicRB",
  "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
  "value_id": "val_27HwIF9YGDzAGrHgifrgIDHAGbX",
  "valid_from": "2026-11-19T09:30:00Z",
  "valid_to": "2026-11-19T09:30:00Z",
  "system_created_at": "2026-11-19T09:30:00Z",
  "system_superseded_at": "2026-11-19T09:30:00Z",
  "superseded_by_user_id": "sup_2EmtFmI3zoylR4ArLSeZJKuFl8g",
  "created_by_user_id": "cre_28qxRmKvFI8JVaS3nUY95qcpzIi",
  "reason": "Leitura confirmada no local."
}

Full binding history including superseded corrections

Logs

GET /temporal/meter-bindings

Returns every recorded binding row for the connection, including rows superseded by later corrections, each with its valid interval and system interval. Results are paged with limit (up to 100, 20 by default) and after. Returns 400 when connection_id is missing; requires temporal:read.

Parameters

connection_idstring · query · required

ID of the connection whose binding history is listed; required.

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Binding rows, newest system version first

Show attributes
dataarray of TemporalFact · required
Show child attributes
idstring · optional
subject_idstring · optional
value_idstring · optional
valid_fromstring (date-time) · optional
valid_tostring (date-time) · optional · nullable
system_created_atstring (date-time) · optional
system_superseded_atstring (date-time) · optional · nullable
superseded_by_user_idstring · optional
created_by_user_idstring · optional
reasonstring · optional
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 403

Permissions temporal:read · Roles: admin, analyst, operations, owner, viewer

curl -X GET "$BUSINESS_API/temporal/meter-bindings" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "tem_2lr6OdduwHv6ur9ASrXCMZhicRB",
      "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
      "value_id": "val_27HwIF9YGDzAGrHgifrgIDHAGbX",
      "valid_from": "2026-11-19T09:30:00Z",
      "valid_to": "2026-11-19T09:30:00Z",
      "system_created_at": "2026-11-19T09:30:00Z",
      "system_superseded_at": "2026-11-19T09:30:00Z",
      "superseded_by_user_id": "sup_2EmtFmI3zoylR4ArLSeZJKuFl8g",
      "created_by_user_id": "cre_28qxRmKvFI8JVaS3nUY95qcpzIi",
      "reason": "Leitura confirmada no local."
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Correct meter binding

Logs

POST /temporal/meter-bindings

State a binding over a valid interval, superseding what it overlaps

Records that meter_id was bound to connection_id from valid_from until valid_to (open-ended when omitted); an empty meter_id states the connection had no meter in that interval. Rows that overlap are superseded rather than deleted and their non-overlapping parts re-created, and repeating an assertion that is already true changes nothing. connection_id, valid_from and reason are required (400 otherwise); the created rows are returned in data with 201, and temporal:write is required.

Body application/json

connection_idstring · required
meter_idstring · required
valid_fromstring (date-time) · required
valid_tostring (date-time) · optional · nullable
reasonstring · required

Returns

201 Created facts

Errors 400 · 403

Permissions temporal:write · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/temporal/meter-bindings" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "connection_id": "con_2wuJTWy9FOCTPGA3noGbHegbLaU",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "valid_from": "2026-11-19T09:30:00Z",
  "valid_to": "2026-11-19T09:30:00Z",
  "reason": "Leitura confirmada no local."
}'
Response 201

Created facts

The tariff in force for a category at a point in time

Logs

GET /temporal/tariff-validity

Answers which tariff was in force for a customer category at a given valid time, as the system recorded it at a given system time. Validity rows are written when tariffs are activated, so this shows the tariff a bill period should have used. Returns 404 when no tariff was in force at that moment and 400 for a missing category or a malformed time; requires temporal:read.

Parameters

categorystring · query · required

Customer category to look up, such as residential, commercial, industrial, institutional or government; required.

as_of_valid_timestring (date-time) · query · optional

RFC 3339 timestamp of the moment the tariff should be in force; defaults to now.

as_of_system_timestring (date-time) · query · optional

RFC 3339 timestamp of what the system believed at that moment, used to reproduce past answers; defaults to now.

Returns

200 Tariff validity fact

Show attributes
idstring · optional
subject_idstring · optional
value_idstring · optional
valid_fromstring (date-time) · optional
valid_tostring (date-time) · optional · nullable
system_created_atstring (date-time) · optional
system_superseded_atstring (date-time) · optional · nullable
superseded_by_user_idstring · optional
created_by_user_idstring · optional
reasonstring · optional

Errors 400 · 403 · 404

Permissions temporal:read · Roles: admin, analyst, operations, owner, viewer

curl -X GET "$BUSINESS_API/temporal/tariff-validity" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "tem_2lr6OdduwHv6ur9ASrXCMZhicRB",
  "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
  "value_id": "val_27HwIF9YGDzAGrHgifrgIDHAGbX",
  "valid_from": "2026-11-19T09:30:00Z",
  "valid_to": "2026-11-19T09:30:00Z",
  "system_created_at": "2026-11-19T09:30:00Z",
  "system_superseded_at": "2026-11-19T09:30:00Z",
  "superseded_by_user_id": "sup_2EmtFmI3zoylR4ArLSeZJKuFl8g",
  "created_by_user_id": "cre_28qxRmKvFI8JVaS3nUY95qcpzIi",
  "reason": "Leitura confirmada no local."
}

The owner of a property at a point in time

Logs

GET /temporal/property-ownership

Answers which customer owned a property at a given valid time, as the system recorded it at a given system time. Ownership rows are written from property transfer events, so a later correction never hides the earlier answer when you query an earlier system time. Returns 404 when no owner is recorded for that moment and 400 for a missing property_id or a malformed time; requires temporal:read.

Parameters

property_idstring · query · required

ID of the property whose owner is looked up; required.

as_of_valid_timestring (date-time) · query · optional

RFC 3339 timestamp of the real-world moment to ask about; defaults to now.

as_of_system_timestring (date-time) · query · optional

RFC 3339 timestamp of what the system believed at that moment, used to reproduce past answers; defaults to now.

Returns

200 Ownership fact

Show attributes
idstring · optional
subject_idstring · optional
value_idstring · optional
valid_fromstring (date-time) · optional
valid_tostring (date-time) · optional · nullable
system_created_atstring (date-time) · optional
system_superseded_atstring (date-time) · optional · nullable
superseded_by_user_idstring · optional
created_by_user_idstring · optional
reasonstring · optional

Errors 400 · 403 · 404

Permissions temporal:read · Roles: admin, analyst, operations, owner, viewer

curl -X GET "$BUSINESS_API/temporal/property-ownership" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "tem_2lr6OdduwHv6ur9ASrXCMZhicRB",
  "subject_id": "sub_2Cg5f6gZ7W8jvEm53ICdbaeNrWe",
  "value_id": "val_27HwIF9YGDzAGrHgifrgIDHAGbX",
  "valid_from": "2026-11-19T09:30:00Z",
  "valid_to": "2026-11-19T09:30:00Z",
  "system_created_at": "2026-11-19T09:30:00Z",
  "system_superseded_at": "2026-11-19T09:30:00Z",
  "superseded_by_user_id": "sup_2EmtFmI3zoylR4ArLSeZJKuFl8g",
  "created_by_user_id": "cre_28qxRmKvFI8JVaS3nUY95qcpzIi",
  "reason": "Leitura confirmada no local."
}