Changelog

Every contract-visible change, newest first. Deprecations additionally go to each key's integration contact by email — see the handbook for the policy.

2026-11-12 — v1 development: metadata endpoints and the error catalogue

• Added GET /v1/meta/status — per-caller status: your key_id, environment (live | test), api_version, server_time, resolved provider_ids, scopes, and a rate_limit block mirroring the response headers. Plus GET /v1/meta/scopes — every scope with a description — and GET /v1/meta/schemas, the OpenAPI 3.0 Schema Object for each public resource (OpenAPI 3.0 Schema Objects, not standard JSON Schema) for dynamic UI generation. Authentication only; no extra scope.
• Added RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset on every rate-limited response; a 429 additionally carries Retry-After. GET /v1/meta/status reports the same budget in its body, so headers and body never disagree.
• Added the error catalogue at /errors/ — every RFC 9457 type URL resolves to a page documenting the status and its machine code. Machine codes: bad_request, unauthorized, forbidden, not_found, conflict, precondition_failed, unprocessable, rate_limited, internal_error, plus client_error — the fallback for any other 4xx not individually listed.

2026-11-09 — v1 development: price types and items

• Added GET /v1/price-types and GET /v1/price-types/{id} — the pricing templates your key's providers use, scoped through the provider → price-type link. Cursor-paginated; filter[status]=active|inactive; sort by id, title or created_at. expand=items inlines the items as embeds.items.data. Scope billing:read.
• Added GET /v1/price-types/{id}/items — the price items on the type for your providers: code, amount, currency (ISO 4217, never an id), price_item_type, threshold, threshold_type, price_instance_status, created_at, updated_at. This is the list an ERP mapping needs to turn the price item codes a provider bills with into GL accounts. Returned complete — this collection is not paginated.
• Note a price type shared by several providers returns only the items priced by your key's providers; another provider's items on the same type are never visible. Items on inactive price instances are included and tagged price_instance_status: inactive, so filter them out if you only bill active prices.

2026-09-22 — v1 development: the project-plan use cases

Built from the member use cases collected in the Public API project plan (asset sync, chatbot directory, ELN linkage, directory sync, proposal-form projects, door access, usage entries). Every change is additive. Preview spec bumped to preview-v13; contracts proposal v10.

• Added GET /v1/users and GET /v1/users/{id} — users of the organizations your key's providers trust, with filter[email] (and filter[email][in]), organization_id, is_disabled, is_verified. This is the lookup a directory sync needs before POST /v1/groups/{id}/members: it turns an institutional identity into the user_id the write takes. Never carries credentials. Scope users:read.
• Added GET /v1/providers, …/{id} — your key's facilities: name, contacts, location, usage policy, timezone, currency. And GET /v1/resource-types, …/{id} — the types in use by your providers' resources plus their parents (parent_id), so every resource_type_id resolves. Scope resources:read.
• Added POST /v1/resources — provision a resource stub from asset-management master data; created offline and invisible to users (status: inactive), configured and switched on in the admin UI. external_reference is the mapping key (unique per provider, 409 on duplicate); resource_type_id is required. And POST /v1/resources/{id}/transitions { "to": "archived" } — ends bookability and hides the resource on disposal; 409 while future bookings exist; repeatable. New scope resources:write. Resources gain external_reference, archived_at and filter[resource_type_id]. Built from member feedback (forum, Aug 2026).
• Note resource status is derived: archived when archived through the API, inactive when the resource is offline or unconfigured, active otherwise. OpenIRIS itself never reads the stored status column, so the API reports the flags that actually govern bookability.
• Added GET /v1/bookings and GET /v1/bookings/{id} — bookings on your providers' resources. Filter on resource_id, provider_id, user_id, group_id, project_id, request_id, status, kind, external_reference, start, end, created_at, updated_at; sort by id, start, end, created_at. Scope bookings:read.
• Note booking status now has five values: confirmed, pending_approval, rejected, cancelled, completed. A rejected booking is neither confirmed nor cancelled and was missing from the earlier derivation.
• Added GET /v1/resources/{id}/current-booking?user_id=…&at=… — the door-access answer: does the user hold a valid booking on the resource at that instant (default now), personally or through a group they are an active member of? Always 200 for a visible resource with access, via (user | group) and the booking in the body. Scope bookings:read.
• Added POST /v1/bookings with "kind": "usage" — record a completed measurement as a usage entry: a booking entirely in the past, no prior reservation, the same row an admin creates by hand. 409 on overlap with an existing booking (never a delete); the user must exist and, with group_id, be an active member. New scope bookings:write. Reservations in advance ("kind": "booking") return 422 in this version.
• Note usage entries are created without charges for now: the pricing engine lives on the internal side of the API and has not yet been shared with the public host. An admin editing the entry in OpenIRIS triggers the usual recalculation.
• Added PATCH /v1/bookings/{id} for external_reference and comments — the ELN round-trip. If-Match required; an empty external_reference clears it. Bookings gain kind, provider_id, parent_booking_id, is_cancelled, cancelled_at.
• Added GET /v1/projects, …/{id}, …/{id}/members and POST /v1/projects — create a project from an external proposal form with members given by email. Emails that match no visible user come back in unmatched_emails; accounts are never created. organization_id may be omitted when group_id is given. external_reference is unique within the organization. Plus POST …/{id}/members and DELETE …/{id}/members/{user_id}, idempotent. New scope projects:write. Built from member feedback (forum, Aug 2026).
• Added charge.cost_center — the cost-center assignment a charge bills to, resolved from its booking or request: provider_code (the SAP WBS / ERP posting code), provider_name, provider_cost_center_id, and any group_code, organization_code, user_code. Null when nothing is assigned. Plus filter[cost_center.provider_code] (eq, in). This is the field a per-cost-center split or a journal posting was missing. Built from member feedback (forum, Aug–Sep 2026).
• Changed (preview spec) charge batches removed — superseded by charge confirmation on 2026-09-14. /v1/charges gains filter[updated_at] in the preview and the ERP guidance now points at filter[confirmed]=true, not status=invoiced. /v1/invoices is parked: confirmation plus export acknowledgements cover the workflow that asked for it.
• Decided SCIM does not terminate at OpenIRIS in v1. Identity provisioning belongs at Auth0 (inbound SCIM on enterprise connections); OpenIRIS provides the email lookup and the membership writes.

2026-09-14 — v1 development: requests and the people on them

• Added GET /v1/requests and GET /v1/requests/{id} — service requests (what most facilities call projects) belonging to your key's providers. Cursor-paginated; filter on status, provider_id, service_id, user_id, group_id, project_id, alt_id and created_at; sort by id, name or created_at. Scope requests:read. Read-only for now — create, transition and the notes/milestones/products sub-collections follow. Built from member feedback (forum, Sep 2026).
• Added GET /v1/requests/{id}/participants — everyone on a request: the owner (role: owner, always first) and the people on its Participants tab, each with email, name and organization_id so a directory or IAM sync can map rows to accounts without a second lookup. Replaces scraping the Participants tab.
• Note the owner is returned whether or not a participant row also exists for them. Only about 30% of requests that have participants carry one for their own owner, so this collection — not a raw membership list — is the complete answer to "who can reach this project?".
• Note request access follows the participant link existing, not its status. Take the whole collection rather than filtering to status: approved; rejecting a participant deletes the row outright. status is null for an owner with no participant row and for a small number of rows that predate the field.
• Changed (preview spec) request.status now lists the seven states OpenIRIS actually stores — pending, active, rejected, closed, inactive, reviewed, discontinued. The earlier preview guessed at draft|active|completed|rejected; no implementation ever served those values. request.provider_id added.
• Note training requests are stored separately and are not part of /v1/requests, so there is no filter[type] yet.

2026-09-14 — v1 development: charge confirmation

• Added charge.confirmed_at — when a billing admin signed the charge off as checked and ready to bill, or null. Set it with PUT /v1/charges/{id}/confirmation, clear it with DELETE on the same path, and set it on up to 500 charges at once with POST /v1/charges/confirmations. New scope billing:write. Built from member feedback (forum, Aug–Sep 2026).
• Added filter[confirmed]=true|false and filter[confirmed_at][gte|gt|lt|lte]. Your ready-to-bill queue is filter[status]=unbilled&filter[confirmed]=true; poll filter[confirmed_at][gte] for what has been signed off since your last pull.
• Note confirmation is not a status value. status holds one value at a time, so a confirmed member would disappear the moment the charge was invoiced. confirmed_at is its own field and survives invoicing and export — it stays the audit answer to "was this signed off, and when?".
• Fixed filter[updated_at] on /v1/charges returned 500 for every operator. It now works and excludes charges whose updated_at is null.

2026-09-01 — v1 development: exports, durable idempotency, per-key limits

• Added POST/GET /v1/charges/{id}/exports — ERP export acknowledgements (the dedup fence). Charge status gains exported, including filter[status]=exported.
• Added GET /v1/openapi.json — the generated specification, publicly served in every environment.
• Idempotency-Key replay is now durable across service restarts.
• Per-key rate-limit raises are now possible (see the handbook).
• Preview spec v9: live surfaces are now marked IMPLEMENTED; corrected resource.class to the real domain values (scheduled | application | service | scheduled_addon | event).

2026-09-01 — v1 development: write surfaces

• Added cost-center writes: POST /v1/cost-centers, PATCH /v1/cost-centers/{id} (inactivation; If-Match required) and filter[code]. New scope cost-centers:write. Built from member feedback (forum, Aug 2026).
• Added group-member administration: POST /v1/groups/{id}/members, DELETE /v1/groups/{id}/members/{user_id}. New scope groups:write. Users are never auto-created. Built from member feedback (forum, Jul 2026).
• Added Idempotency-Key requirement on all POST/PATCH requests, with byte-identical replay.

2026-09-01 — v1 development: read surfaces

• Added GET /v1/resources and GET /v1/resources/{id} — provider-scoped resource directory.
• Added GET /v1/charges, …/{id}, …/{id}/line-items — the primary ERP surface over booking and request charges. (Product-order charges follow in a later increment.)
• Added collection conventions everywhere: envelope, cursor pagination (forward-only in v1), filter[field][op] with per-field safelists, multi-key sort, RFC 9457 errors with code + trace_id, ETag/If-None-Match on single reads.

2026-08 — preview v8: first feedback-driven revision

• All five member suggestions on the feedback forum addressed: cost-center writes and group-member writes committed to v1; project creation and resource provisioning proposed for v1.1; charge batches (period-close vetting) opened as a design proposal.
• Invoice model corrected: an invoice may span many cost centers.
• Four provisioning scopes added, kept separate from end-user scopes.

2026-04 — preview v7: contract proposal published

• Full proposed surface (98 paths) published for member review at api-preview.openiris.io with the feedback forum attached.