# Grindzero — public HTTP API (pointers for humans & AI tools)

> Same Next.js deployment serves **Admin** and **API** hostnames. Use absolute URLs below in production; relative paths (`/docs`, `/openapi.yaml`) work on either host for a given deployment.

## Human-readable docs (HTML)

- https://api.grindzero.app/docs
- https://admin.grindzero.app/docs

## OpenAPI 3 (YAML)

- https://api.grindzero.app/openapi.yaml
- https://admin.grindzero.app/openapi.yaml

## Versioned API (`/api/v1/*`)

Protected routes (require organization API key unless noted):

- `GET /api/v1/orgs` — organizations the key may access
- `PATCH /api/v1/orgs/{orgId}` — update organization display name
- `GET /api/v1/sites` — worksites
- `GET /api/v1/surpluses` — surplus orders (cursor pagination)
- `GET /api/v1/receiving-points` — receiving points
- `GET /api/v1/reports/summary` — summary report
- `GET /api/v1/trucks` — organization trucks (TECH-139)
- `POST /api/v1/trucks` — create truck (TECH-139)
- `GET /api/v1/members` — active org members (TECH-139)

Scopes: `read:orgs`, `write:orgs:self`, `read:data`, `write:data`, or `*`. See OpenAPI and `/docs` for details.

## Technical design (repository, not mirrored on API host)

- Canonical Finnish + internal contract: **`docs/API-DESIGN.md`** in the **gz-admin-app** repository.
- Partner quick reference, onboarding, changelog policy, roadmap: **`docs/PUBLIC-DOCS.md`** (same repository).