Create a project measurement

Projects module

POST/project-measurementsprojectMeasurements.create

A figure measured on a project (Section 4.10) for one metric, day and source. A null value records that the figure was not measured (Unmeasured), never zero. Correcting the value, unit or day needs correction_reason and writes the change to the correction ledger. Who recorded it and when are created_by and created_at. Creates a project measurement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.

Requires the capability projects.gate.evidence.write.
OAuth scopes: projects.
Send an Idempotency-Key header. A replay with the same key returns the original response.
Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.

Request body: ProjectMeasurementCreate

projectMeasurements.create: ProjectMeasurementCreate
Field	Type	Required	Description
project_id	string (uuid)	Yes	Identifier of the project.
metric_code	string	Yes	Metric (app.measurement_metrics).Constraints: pattern ^[a-z][a-z0-9_]*$
measured_on	string (date)	No	Day the figure covers, on the project's calendar; today there when omitted, never later.
value	number \| null	No	The figure in unit_code; null when not measured.
unit_code	string \| null	No	Unit of the figure, of the metric's dimension.Constraints: pattern ^[a-z][a-z0-9_]*$
source	"Manual" \| "Import" \| "Integration"	No	How the figure reached XOS.
source_reference	string \| null	No	What the figure came from, such as an invoice, a meter reading or a file name.Constraints: length 1 to 300
source_uri	string \| null	No	Link to the source: an http(s) URL or a URN.Constraints: length 1 to 2000
note	string \| null	No	Note.Constraints: length 1 to 2000

{
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "metric_code": "waste_generated",
  "measured_on": "2026-10-08",
  "value": 1200,
  "unit_code": "kg",
  "source": "Import",
  "source_reference": "Hauler invoice 4471",
  "source_uri": "https://hauler.example/invoices/4471",
  "note": "Two roll-off containers."
}

Response 201: ProjectMeasurement

projectMeasurements.create: ProjectMeasurement
Field	Type	Required	Description
id	string (uuid)	Yes	Identifier of the project measurement.
org_id	string (uuid)	Yes	Identifier of the owning organization, derived from the parent row and never accepted from the caller.
created_at	string (date-time)	Yes	When the row was created.
created_by	string (uuid) \| null	Yes	Identifier of the person who created the row.
updated_at	string (date-time)	Yes	When the row was last updated.
updated_by	string (uuid) \| null	Yes	Identifier of the person who last updated the row.
project_id	string (uuid)	Yes	Identifier of the project.
metric_code	string	Yes	Metric (app.measurement_metrics).Constraints: pattern ^[a-z][a-z0-9_]*$
measured_on	string (date)	Yes	Day the figure covers, on the project's calendar; today there when omitted, never later.
value	number \| null	Yes	The figure in unit_code; null when not measured.
unit_code	string \| null	Yes	Unit of the figure, of the metric's dimension.Constraints: pattern ^[a-z][a-z0-9_]*$
source	"Manual" \| "Import" \| "Integration"	Yes	How the figure reached XOS.
source_reference	string \| null	Yes	What the figure came from, such as an invoice, a meter reading or a file name.Constraints: length 1 to 300
source_uri	string \| null	Yes	Link to the source: an http(s) URL or a URN.Constraints: length 1 to 2000
note	string \| null	Yes	Note.Constraints: length 1 to 2000

{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "metric_code": "waste_generated",
  "measured_on": "2026-10-08",
  "value": 1200,
  "unit_code": "kg",
  "source": "Import",
  "source_reference": "Hauler invoice 4471",
  "source_uri": "https://hauler.example/invoices/4471",
  "note": "Two roll-off containers."
}

Code samples

curl -X POST "$XOS_BASE_URL/project-measurements" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","metric_code":"waste_generated","measured_on":"2026-10-08","value":1200,"unit_code":"kg","source":"Import","source_reference":"Hauler invoice 4471","source_uri":"https://hauler.example/invoices/4471","note":"Two roll-off containers."}'

const { data } = await xos.projectMeasurements.create({
    "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "metric_code": "waste_generated",
    "measured_on": "2026-10-08",
    "value": 1200,
    "unit_code": "kg",
    "source": "Import",
    "source_reference": "Hauler invoice 4471",
    "source_uri": "https://hauler.example/invoices/4471",
    "note": "Two roll-off containers."
  });

response = xos.project_measurements.create({"project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "metric_code": "waste_generated", "measured_on": "2026-10-08", "value": 1200, "unit_code": "kg", "source": "Import", "source_reference": "Hauler invoice 4471", "source_uri": "https://hauler.example/invoices/4471", "note": "Two roll-off containers."})

xos project-measurements create --data '{"project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","metric_code":"waste_generated","measured_on":"2026-10-08","value":1200,"unit_code":"kg","source":"Import","source_reference":"Hauler invoice 4471","source_uri":"https://hauler.example/invoices/4471","note":"Two roll-off containers."}'