HTTP API (v1)

GET /api/v1/orgs

Returns the organization bound to the API key, including `parent_id` and `children` (direct sub-orgs: `id`, `name`, `status`). `data` has one row. Requires scope `read:orgs` or `*`.

Authorization: Bearer gz_app_<your_api_key>

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Construction",
      "status": "approved",
      "parent_id": null,
      "children": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440111",
          "name": "Acme Concrete Plant",
          "status": "approved"
        }
      ],
      "business_code": "1234567-8",
      "street_address": "Mukulakuja 4 A 9",
      "postal_code": "04300",
      "city": "Tuusula",
      "invoice_email": "billing@acme.example",
      "created_at": "2026-01-15T08:00:00.000Z",
      "updated_at": "2026-08-25T12:00:00.000Z"
    }
  ],
  "meta": {
    "count": 1
  }
}

curl -sS "https://api.grindzero.app/api/v1/orgs" \
  -H "Authorization: Bearer API_KEY"

PATCH /api/v1/orgs/{orgId}

Partial update of the organization bound to the API key. Path `orgId` must be that same UUID. Requires scope `write:orgs:self` or `*`.

Content-Type: application/json
Authorization: Bearer gz_app_<your_api_key>

{
  "name": "Acme Construction",
  "business_code": "1234567-8",
  "street_address": "Mukulakuja 4 A 9",
  "postal_code": "04300",
  "city": "Tuusula",
  "invoice_email": "billing@acme.example"
}

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Construction",
    "status": "approved",
    "parent_id": null,
    "children": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440111",
        "name": "Acme Concrete Plant",
        "status": "approved"
      }
    ],
    "business_code": "1234567-8",
    "street_address": "Mukulakuja 4 A 9",
    "postal_code": "04300",
    "city": "Tuusula",
    "invoice_email": "billing@acme.example",
    "created_at": "2026-01-15T08:00:00.000Z",
    "updated_at": "2026-08-25T12:00:00.000Z"
  }
}

curl -sS -X PATCH "https://api.grindzero.app/api/v1/orgs/ORG_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"name":"Acme Construction","city":"Tuusula"}'

GET /api/v1/orgs/{orgId}

The key org or a direct child. Other orgs → `404` `org_not_found`. Scope `read:orgs` or `*`.

curl -sS "https://api.grindzero.app/api/v1/orgs/ORG_ID" \
  -H "Authorization: Bearer API_KEY"

POST /api/v1/orgs

Creates a sub-organization under the key org. Does not create a top-level parent. Optional `parent_id` must be the key org. Copies the parent’s active `org_admin` memberships onto the child. Scope `write:orgs:self` or `*`.

{
  "name": "Acme Concrete Plant",
  "city": "Vantaa"
}

Required: `name`. Optional: `parent_id`, `business_code`, `street_address`, `postal_code`, `city`, `invoice_email`. `409` `org_name_conflict` if the name is already taken.

curl -sS -X POST "https://api.grindzero.app/api/v1/orgs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"name":"Acme Concrete Plant","city":"Vantaa"}'

GET /api/v1/sites/{siteId}

Returns one worksite (including archived) plus `members` and `metadata`. Requires scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/sites/SITE_ID" \
  -H "Authorization: Bearer API_KEY"

PATCH /api/v1/sites/{siteId}

Partial update. `customer_id` cannot be changed. `metadata` replaces the whole object. `409` if archived. Scope `write:data` or `*`.

curl -sS -X PATCH "https://api.grindzero.app/api/v1/sites/SITE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"name":"Helsinki Central A"}'

DELETE /api/v1/sites/{siteId}

Archives the worksite (`deleted_at`). `409` if already archived. Scope `write:data` or `*`.

curl -sS -X DELETE "https://api.grindzero.app/api/v1/sites/SITE_ID" \
  -H "Authorization: Bearer API_KEY"

POST /api/v1/sites/{siteId}/restore

Clears the archive. `409` if the worksite is not archived. Scope `write:data` or `*`.

curl -sS -X POST "https://api.grindzero.app/api/v1/sites/SITE_ID/restore" \
  -H "Authorization: Bearer API_KEY"

GET /api/v1/sites/{siteId}/members

Worksite people (`site_members`): first name, last name, phone, role. No email. The same list is on `GET /sites/{id}` as `members`. Scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/sites/SITE_ID/members" \
  -H "Authorization: Bearer API_KEY"

GET /api/v1/surpluses/{surplusId}

One surplus + signed waybill URL. `404` `surplus_not_found` if the origin worksite is not in this org or the row is archived. Scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/surpluses/SURPLUS_ID" \
  -H "Authorization: Bearer API_KEY"

GET /api/v1/surpluses/{surplusId}/log

Surplus change log (`surplus_log`): `id`, `created_at`, `status_from`, `status_to`, `message`, `user_id` (nullable). Oldest first. Scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/surpluses/SURPLUS_ID/log" \
  -H "Authorization: Bearer API_KEY"

PATCH /api/v1/surpluses/{surplusId}

Partial update matching the org-admin edit form: `volume_m3`, `additive`, `additive_billed_to` (`origin_site`|`truck`), `material_grade`, `manufacturer`, `description`, `notes`, `site_id`, `to_receiving_point_id`, `status`. Not `created_at`/`delivered_at` or truck/driver (superadmin). Route is locked after delivery (`422` `route_locked`). `delivered` requires a waybill. Scope `write:data` or `*`.

{
  "volume_m3": 8.5,
  "material_grade": "C30/37",
  "manufacturer": "Rudus",
  "description": "Read from waybill"
}

curl -sS -X PATCH "https://api.grindzero.app/api/v1/surpluses/SURPLUS_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"volume_m3":8.5,"material_grade":"C30/37"}'

POST /api/v1/surpluses

Creates a surplus from an origin worksite. Required: `site_id`, `volume_m3`. Optional: `to_receiving_point_id`, `truck_id`, `additive`, `additive_billed_to` (`origin_site`|`truck`), `material_grade`, `manufacturer`, `description`, `notes`. Truck is not required. Scope `write:data` or `*`.

{
  "site_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "volume_m3": 8.5,
  "to_receiving_point_id": "cccccccc-dddd-eeee-ffff-000000000000"
}

HTTP 201. `truck_id` must be this org's (or a granted partner's) truck. `422` `truck_not_found` / `site_not_found` / `site_archived`.

curl -sS -X POST "https://api.grindzero.app/api/v1/surpluses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"site_id":"SITE_ID","volume_m3":8.5}'

POST /api/v1/surpluses/{surplusId}/waybill

Upload a waybill image (multipart, field `file`). JPEG/PNG/WebP, max 10 MB. Required before `status: delivered`. Scope `write:data` or `*`.

curl -sS -X POST "https://api.grindzero.app/api/v1/surpluses/SURPLUS_ID/waybill" \
  -H "Authorization: Bearer API_KEY" \
  -F "file=@waybill.jpg"

GET /api/v1/receiving-points/{rpId}

Returns one receiving point, including `open_hours` and `photos` (signed URLs, same pattern as waybill). Requires scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/receiving-points/RP_ID" \
  -H "Authorization: Bearer API_KEY"

PATCH /api/v1/receiving-points/{rpId}

Partial update. `site_id` cannot be changed. `409` if archived. Scope `write:data` or `*`.

curl -sS -X PATCH "https://api.grindzero.app/api/v1/receiving-points/RP_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"capacity_m3":600}'

DELETE /api/v1/receiving-points/{rpId}

Archives the receiving point. `409` if already archived. Scope `write:data` or `*`.

curl -sS -X DELETE "https://api.grindzero.app/api/v1/receiving-points/RP_ID" \
  -H "Authorization: Bearer API_KEY"

POST /api/v1/receiving-points/{rpId}/restore

Clears the archive. `409` if the point is not archived. Scope `write:data` or `*`.

curl -sS -X POST "https://api.grindzero.app/api/v1/receiving-points/RP_ID/restore" \
  -H "Authorization: Bearer API_KEY"

GET /api/v1/reports/loads

Source rows for month-end. Same origin-site scope and `created_at` window as summary. `additive_usage_m3` is ceil per load (same as admin `/reports`). Keyset pagination. Scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/reports/loads?from=2026-05-01&to=2026-05-31" \
  -H "Authorization: Bearer API_KEY"

GET /api/v1/billing/additive-usage

Monthly additive usage (m³) billed to this org. Same ceil rule as `/manager/billing`. Month is UTC from `delivered_at` else `created_at`. Scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/billing/additive-usage?from=2026-05-01&to=2026-05-31" \
  -H "Authorization: Bearer API_KEY"

GET /api/v1/trucks/{truckId}

One truck plus last known position. `404` `truck_not_found` if the truck is not an active vehicle in this org. Scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/trucks/TRUCK_ID" \
  -H "Authorization: Bearer API_KEY"

PATCH /api/v1/trucks/{truckId}

Partial update. Writable: `driver_id` (or `driverId`), `name`, `license`, `country`, `capacity_m3` (or `capacity`), `notes`. `driver_id` must be an active member from `GET /api/v1/members`; `null` unassigns. GPS is read-only. Scope `write:data` or `*`.

{
  "driver_id": "713e48dc-d5b9-424f-98a0-c307de3c46a1",
  "name": "Volvo FH",
  "capacity_m3": 16
}

At least one field. Changing driver releases them from any other truck in the org (same as admin PATCH).

curl -sS -X PATCH "https://api.grindzero.app/api/v1/trucks/TRUCK_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"driver_id":"DRIVER_PROFILE_ID"}'

GET /api/v1/members/{memberId}

One membership (including inactive). `404` `member_not_found` if the profile is not in this org. Scope `read:data` or `*`.

curl -sS "https://api.grindzero.app/api/v1/members/MEMBER_ID" \
  -H "Authorization: Bearer API_KEY"

PATCH /api/v1/members/{memberId}

Partial update: `first_name`, `last_name`, `phone`, `role`, `active`. `role: null` or `DELETE …/role` resets to base `member`. `active: false` leaves this org. Cannot assign `org_admin`. Scope `write:data` or `*`.

{
  "first_name": "Alex",
  "role": "driver",
  "active": true
}

curl -sS -X PATCH "https://api.grindzero.app/api/v1/members/MEMBER_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"role":"driver"}'

DELETE /api/v1/members/{memberId}

Same as PATCH `{ "active": false }`. `409` `already_inactive` if already left. Releases this org's trucks where the member is the assigned driver.

curl -sS -X DELETE "https://api.grindzero.app/api/v1/members/MEMBER_ID" \
  -H "Authorization: Bearer API_KEY"

PUT /api/v1/members/{memberId}/role

Grants an operational role (one per membership): PUT `{ "role": "driver" }`. Allowed: `member`, `driver`, `site_manager`, `factory_manager`, `additive_supplier`. Demoting a driver releases trucks. Scope `write:data` or `*`.

curl -sS -X PUT "https://api.grindzero.app/api/v1/members/MEMBER_ID/role" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -d '{"role":"driver"}'

DELETE /api/v1/members/{memberId}/role

Removes the special role: resets `role` to `member`. Does not deactivate membership (use `DELETE /members/{id}` for that).

curl -sS -X DELETE "https://api.grindzero.app/api/v1/members/MEMBER_ID/role" \
  -H "Authorization: Bearer API_KEY"