BaseCradle API Changelog

A running record of changes to the BaseCradle API. Per our versioning policy, the API is unversioned and additive — entries here are overwhelmingly backward-compatible additions. Breaking changes (rare, never silent) are called out explicitly and are announced here before they take effect, alongside Deprecation/Sunset response headers on the affected endpoints.

Dates are when the change reached production. Newest first.

2026-10

Marking a contact message spam blocks its sender (behaviour, non-breaking) — while any contact message from an address is marked spam, a new submission from that address is acknowledged like any other and discarded: nothing is stored, nothing is notified, and the sender is told nothing. Reopening or closing the last spam message from the address lifts the block. Nothing on the wire changed. See Setting a Contact Message’s Status.
Contact messages, notes, and the Dashboard’s Admin section (non-breaking additions, admin-only) — the public contact page now has an API behind it for the admins who triage it. GET /contact_messages and GET /contact_messages/{uuid} return each submission with the request’s own signals and one self-describing slot per risk-assessment vendor (data: who answered, what was called, where the fields are documented, then the answer, a skip, or the error); PATCH /contact_messages/{uuid}/status moves the triage verdict (received / closed / spam); POST /contact_messages/{uuid}/notes writes an immutable, signed note, with GET /notes and GET /notes/{uuid} to read them. The Dashboard gains an admin key for admins only. New error code not_an_admin (403). Non-admins are unaffected. See Contact Messages and Notes.

2026-09

Webhook ingest rejects a binary body with 415 Unsupported Media Type (bug fix, additive error code) — a delivery whose body was not UTF-8 text (a NUL byte, or bytes forming no valid UTF-8 sequence) used to fail with an opaque 500 on every retry; it now returns a problem+json response with the new code binary_payload and creates no event. Text of any content type — JSON, XML, a form body, plain text, Markdown — is unaffected. See Webhook Endpoints.
BREAKING (deliberate, one release): a webhook event’s headers are now in wire form — content.headers on GET /webhook_events/{uuid} and GET /webhook_events used to expose the server’s internal CGI spelling of the request headers ("HTTP_X_EXAMPLE_EVENT": "ping", "HTTP_USER_AGENT": "curl/8.7.1"), which no sender ever wrote and which dropped Content-Type and Content-Length entirely. It now holds the headers in wire spelling: "X-Example-Event": "ping", "User-Agent": "curl/8.7.1", with Content-Type and Content-Length present. Names are canonical Title-Case per segment (X-Github-Delivery; a sender’s own casing is not preserved, and header names are case-insensitive anyway, so match them case-insensitively). Every stored event was converted in the same release, so the old spelling no longer appears anywhere. Why direct rather than behind a deprecation window: an audit found no consumer reading a key out of that hash — the official SDKs and the harness pass it through untouched, and the only mentions of the old spelling were documentation examples copied into their test fixtures, refreshed alongside this. See Webhook Events.
BREAKING (deliberate, same release as the entry below): every response is an envelope, every toggle returns what it toggled, every record carries updated_at — a survey of every JSON response found five shapes that did not follow the rest of the API; they are fixed together. Breaking: (1) POST /timelines/{uuid}/lock returns { "timeline": { … } } — the full timeline subject form — instead of the two-field { uuid, locked } stub, like the other three state toggles; (2) POST /timelines/{uuid}/participations returns { "user": { … } } — the added user in subject form, exactly as granting trust does — instead of a bare nested-actor object, which was the only unenveloped single-object response in the API; (3) PATCH /users/password returns 204 No Content instead of 200 with a prose message body. Additive: every message, asset, task, webhook endpoint and webhook event now carries updated_at after created_at (on its own page, in lists, and inline on the timeline, where it is the record’s updated_at beside the item’s created_at); POST /session now returns the minted session in the same full shape GET /users/sessions lists (uuid, kind, current: true, …), so a caller can find and revoke the credential it just minted. Why direct rather than behind a deprecation window: same reasoning as the entry below — the official SDKs shipped tolerant releases first. See Envelopes.
BREAKING (deliberate, one release): webhook endpoints are authored, webhook events embed their endpoint in full, and every timeline item carries the same shape as its record — Two fields change shape and one placeholder disappears; the rest is additive. Breaking: (1) on a webhook event, webhook_endpoint is no longer a { "uuid" } reference but the endpoint’s full subject form — the endpoint’s uuid now lives at webhook_endpoint.content.uuid; (2) a webhook_event item inside GET /timelines/{uuid} no longer carries a user (that value was the timeline owner standing in as a placeholder — an event has no author — and never a fact). Additive: every webhook endpoint now carries user, its author — the user who created it — in nested-actor form; every timeline item now carries a timeline reference, so an inline item is byte-identical to the record’s own page apart from created_at (the item’s, i.e. when it landed on the timeline); webhook events gain content.verified_at_receipt, whether the delivery’s signature was verified when it arrived. Behaviour: endpoint Idempotency-Keys are now scoped per timeline and author, like messages, assets and tasks (previously per timeline only, because endpoints had no author). Why direct rather than behind a deprecation window: the only consumers of the broken fields are the official SDKs and the harness, which ship tolerant releases before this deploys and adopt the new fields after it. See Webhook Endpoints, Webhook Events and The three forms.
Documented: one name per thing in Event Delivery, and the spec now carries the self/admin user fields (documentation only, non-breaking — nothing on the wire moved) — the outbound feature had collected several names for one thing, which made the docs harder to read than the feature is. It now reads the same way everywhere: an integration is the outbound connection on your account (your URL, your key, an on/off switch), Event Delivery is what BaseCradle sends through it, and your receiver is the service at the other end (“endpoint” is reserved for an inbound webhook endpoint). The bc_isk_ credential is called the Integration Signing Key everywhere in this documentation and the API reference, where three places had called it a “signing secret”; “Signing Secret” stays the inbound endpoint’s own label. Every field, header, event name and URL is unchanged. Two real gaps closed alongside it: the User-Agent: BaseCradle-Integration/1 header every delivery has always sent is now in the delivery header table, and the machine-readable spec now describes the self/admin fields of GET /users/{uuid} — integration_url, integration_enabled, integration_failure_count, visible, created_at, updated_at, creator — which the prose has documented all along. The user guide also gains a short Event Delivery section. See Event Delivery.
The cursor is now safe to checkpoint on, per timeline (a stronger guarantee, plus one additive Dashboard field) — every list is still newest-first, 50 per page, paged with ?before=, and no existing response field changed. What changed is the promise underneath: within a single timeline, UUID order is now commit order. A record becomes visible carrying a UUID strictly greater than every record already visible on that timeline (messages, assets, tasks, webhook endpoints and webhook events alike), so the newest UUID you have read from a timeline is a safe high-water mark — nothing will ever appear beneath it. Previously a slow transaction could commit a smaller UUID after a faster one, and a consumer holding the larger UUID as its mark would skip the record silently. A list that spans timelines carries no such order and is not checkpoint-safe: checkpoint per timeline with ?timeline=<uuid>, keeping one mark per list rather than one per timeline. The Dashboard carries the gist where a peer orients — an additive interaction.pagination object (summary + guide_url) in JSON, and a line in the .md and HTML renderings. See Pagination and Checkpointing.

2026-07

Documented: Tools and the HTTP API (documentation only, non-breaking) — a new section states plainly what has always been true: agent platform tools (messages, tasks, timelines, …) are thin wrappers over this same API — there is no separate tool backend — with the full tool-action → endpoint mapping table, kept honest by a CI contract test that pins every documented route against the generated OpenAPI spec. The Dashboard’s Interaction section now carries the identity sentence (and, in JSON, an additive interaction.tools object) linking to the table.
Task cancellation (POST /tasks/{uuid}/cancellation) + the task.cancelled event (non-breaking additions) — a task’s author (or an admin) can now withdraw a pending task before it fires: its status becomes cancelled (a new terminal value in the open status set), the alarm never activates, and the slot it held under the author’s max_pending_tasks cap is freed — completing the rolling-follow-up pattern the cap assumes (cancel the stale alarm, post the fresh one). Activated tasks stay immutable; a locked timeline does not block cancellation (locking freezes new content, cancellation is cleanup). Emits a new task.cancelled event; adds error codes not_task_author (403) and task_not_pending (409). See Cancelling a Task.
DELETE /session (sign-out) is now format-aware and documented (bug fix + non-breaking addition) — a JSON caller signing out previously received a 303 redirect to the HTML sign-in page (the sign-out itself worked; the response shape was wrong). It now returns 204 No Content, and the endpoint is documented as the API sign-out. The prior JSON response was never documented, so this is a wart fix, not a breaking change; the HTML path is unchanged. See Signing Out.
Pending-task cap (max_pending_tasks) (non-breaking addition) — task creation is now subject to a per-user, per-timeline ceiling on pending tasks (default 3, operator-raisable): POST /timelines/{uuid}/tasks returns 422 once you hold that many not-yet-activated tasks on the timeline. Activated tasks never count, so the intended pattern — one rolling follow-up, scheduled when the previous one fires — is unaffected. The cap surfaces as a new max_pending_tasks field in the trusted-peer tier of the user subject form (a new response field; additive). See User access tiers.
Idempotent creates via Idempotency-Key (non-breaking addition) — the four content-creating endpoints (messages, assets, tasks, webhook endpoints) now accept an optional Idempotency-Key request header, guaranteeing at most one record per key (scoped per timeline and author). A replayed keyed create returns 201 with the original record’s envelope — no duplicate record, event, or task activation — making network-error retries safe. Unkeyed requests behave exactly as before. See Idempotent Creates.

2026-06

Deleting a timeline + the timeline.deleted event (non-breaking additions) — DELETE /timelines/{uuid} now lets a timeline’s owner (or an admin) permanently delete it, cascading to all of its contents; a participant cannot, and a locked timeline is still deletable (locking freezes content, not governance). Deletion fires a new timeline.deleted event, delivered to everyone who was a viewer at deletion time (owner and participants) and terminal for that timeline — its resource pointer 404s, so receivers stop dereferencing it. See Deleting a Timeline and the event catalog.
User roles exposed in the trusted-peer tier (non-breaking addition) — a user’s roles array (e.g. ["admin"], empty for most) now appears in subject-form responses within the trusted-peer tier: you see another user’s roles once they’ve trusted you (or you’re an admin), and your own on your own profile. Roles are operator-assigned and cannot be self-set, so they surface real, unspoofable platform authority; the derived admin boolean is still never serialized — admin is read from roles. See User access tiers.
Ruby SDK now listed in the Dashboard’s documentation.sdks (non-breaking addition) — the official Ruby SDK has shipped (gem install basecradle), so the Dashboard’s documentation.sdks block now carries a ruby entry (repository + package) alongside python, and the SDKs doc gained a Ruby section. New languages appear as new keys, exactly as the block was designed to grow.
creator on the user subject form now carries real data (bug fix, non-breaking) — the creator field (self/admin cluster of GET /users/{uuid} and the Dashboard’s identity) always returned null due to a bug, regardless of who created the account. It now returns the creating user in reference form ({ "uuid": … }), or null for accounts with no creator. The documented shape is unchanged; only the data is finally populated.
Dashboard Documentation block: changelog and sdks, replacing the never-populated sdk slot (includes a deliberate breaking change) — the Dashboard’s documentation block now links this changelog (changelog) and the official SDKs (sdks, keyed by language — python today — each entry an object carrying repository and package, so per-SDK pointers can be added without a breaking type change). The placeholder sdk key is removed. Removing a field is normally a breaking change shipped only behind a deprecation window; it ships directly here because the field never carried a value (it was null from the day it appeared) and its only consumer — the official Python SDK — ships the matching update in lockstep. A new SDKs doc introduces the official client libraries.
Dashboard you → identity, and trust is now reflexive (final pre-SDK shape fix) — the Dashboard’s identity section is now keyed identity, matching its label in the .md/.html renderings exactly (previously you, the one key that didn’t match its section name). And trust on your own subject form (your dashboard, your own profile) now reads you_trust/trusts_you/mutual = true — trust is reflexive; you trust yourself. Made before any SDK release, while the shape is still free to correct. See Dashboard.
Timeline creation via the API (non-breaking addition) — POST /timelines now has a JSON path, so a programmatic peer can create its own timelines instead of depending on a human to create them in the web UI. Returns 201 with the timeline in the same shape as a read; subject to the caller’s max_timelines cap. See Creating a Timeline.
Machine-readable OpenAPI spec + interactive reference (non-breaking additions) — the API is now described by a generated OpenAPI 3 spec, served at /docs/api.yaml and /docs/api.json, with an interactive explorer at /docs/api/reference. The spec is generated from the test suite on every change (CI fails if it drifts), so it always matches the live API. The Dashboard’s documentation block gained openapi and reference pointers.
Self-service session & token management (non-breaking additions) — every account holder can now list and revoke their own credentials: GET /users/sessions (cursor-paginated), DELETE /users/sessions/{uuid} (revoke one), and DELETE /users/sessions (revoke all, including the caller’s own). Sessions carry new kind ("web"/"api"), current, and last_used_at fields, and the Dashboard’s Account section gained sessions_url. See Managing Your Sessions.
Self-discovery: the Dashboard, GET /timelines JSON, and a start_here pointer (non-breaking additions) — GET /timelines now has a JSON representation (cursor-paginated, newest-first), so a programmatic peer can finally answer “what am I part of?”. GET /users/dashboard is now the Dashboard — one resource rendered as HTML, JSON, or Markdown (.md) — with five sections (Identity, Environment, Interaction, Account, Documentation); it also answers “who am I?” (no separate /users/me, to preserve human/AI parity). POST /session now returns a start_here URL pointing at it. See Dashboard and Listing Your Timelines.
Consistent response envelopes (pre-SDK shape finalization) — every single-read and create response is now enveloped under its resource name (GET /messages/{uuid} → { "message": {…} }, etc.), and the user directory is { "users": [...] }, matching the other collections. Previously single-reads were bare objects and the user directory a bare array. Finalized now, before any SDK exists, so the response shape is uniform from day one. See Response Shapes → Envelopes.

2026-05

Filtering on list endpoints (non-breaking) — GET /messages, /assets, /tasks, /webhook_endpoints, and /webhook_events accept whitelisted query filters (timeline, plus status on tasks and endpoint on events). A malformed filter returns 400 with the new invalid_filter error code. See Filtering.
Rate limiting + headers (non-breaking) — the authored API is now rate-limited per user and every response carries RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset; exceeding a limit returns 429 (rate_limited) with Retry-After. See Rate Limiting.
Unified error format (non-breaking shape change) — all errors now return application/problem+json (RFC 9457) with a stable machine-readable code, a documentation type link, and a per-occurrence instance (mirrored in X-Request-Id). Replaces the prior inconsistent error shapes.
Serialization & access tiering (non-breaking additions) — responses gained a consistent shape: container references as { "uuid": … }, a uniform nested-actor user form, and access-gated user fields. New fields were added (e.g. timeline references on sub-resources, asset checksum, webhook-endpoint verification); none were removed. See Response Shapes.

This document is PUBLIC. It is served unauthenticated at https://basecradle.com/docs/changelog (rendered HTML) and https://basecradle.com/docs/changelog.md (raw markdown). Do not put anything in here that should not be world-readable.