Incidents

Base URL: $BUSINESS_API

The object

resource_typestring · optional
resource_idstring · optional
metadataobject · optional
The object
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

List water network incidents

Logs

GET /incidents

Returns the tenant's network incidents (leaks, bursts, pressure drops, contamination, illegal connections) with severity, status, location and timestamps. Results are cursor-paginated (default 20, maximum 100); the handler also accepts incident_type, severity, status and service_area_id filters. Requires the operations:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Incidents

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/incidents" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Incidents

Report a water leak or incident

Logs

POST /incidents

Records a new incident with status reported and a generated INC-<year>-<suffix> number, and returns it with 201. incident_type and description are required (400 otherwise); severity defaults to medium, and asset, service area and coordinates are optional. Requires the operations:write permission.

Returns

201 Incident reported

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

curl -X POST "$BUSINESS_API/incidents" \
  -H "Authorization: Bearer sk_test_..."
Response 201

Incident reported

Get incident details

Logs

GET /incidents/{id}

Returns one incident with its number, type, severity, status, linked asset and service area, coordinates and reported and resolved times. Returns 404 when it is not in the tenant. Requires the operations:read permission.

Parameters

idstring · path · required

Identifier of the incident (an inc_ prefixed ID) within the current tenant.

Returns

200 Incident details

Permissions operations:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/incidents/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Incident details

Mark incident resolved

Logs

POST /incidents/{id}/resolve

Sets the incident's status to resolved, stamps resolved_at with the current time and returns the updated incident. The status is not checked first, so resolving an already resolved incident moves resolved_at forward. Returns 404 for an unknown incident. Requires the operations:write permission.

Parameters

idstring · path · required

Identifier of the incident to resolve within the current tenant.

Returns

200 Incident resolved

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

curl -X POST "$BUSINESS_API/incidents/{id}/resolve" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Incident resolved

Get the metadata of a incident

Logs

GET /incidents/{id}/metadata

Returns the custom key-value metadata attached to the incident, as an object of string values. The incident must exist in the tenant, otherwise 404. Requires the business:metadata:read permission.

Parameters

idstring · path · required

Identifier of the incident whose metadata is read, at most 120 characters.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/incidents/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /incidents/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the given keys into the incident's metadata and returns the full resulting set: keys in the body are added or overwritten, an empty string value deletes that key, and keys not in the body are kept. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and the incident may carry at most 50 keys (400 otherwise). Requires the business:metadata:write permission; 404 when the incident does not exist.

Parameters

idstring · path · required

Identifier of the incident whose metadata is merged, at most 120 characters.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/incidents/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}