API v1 Changelog

2026-09-05 - Public Platform Knowledge URLs

Compatibility: additive public documentation contract.

• A published knowledge card is available at {DOCS_PUBLIC_ORIGIN}/{localePath}/kb/{topic}/{slug}/, where localePath is en or zh-tw and slug is the third dot-separated segment of the card ID.
• Its machine-readable Markdown uses the same path with .md in place of the trailing slash. The public locale projection is available at {DOCS_PUBLIC_ORIGIN}/{localePath}/kb/index.json.
• These URLs contain only the public projection. Internal source references, assertions, content digests, and schema metadata are excluded.

2026-09-05 - Agent Platform Knowledge API

• Added agent-authenticated GET /api/v1/knowledge/index?locale=&topic= and GET /api/v1/knowledge/documents/{documentKey}?locale= resources. User callers receive 403; Platform Knowledge is global and agent callers do not require document ownership.

2026-09-05 - Cron Validation and Execution Limits

Compatibility: stricter validation for Cron create, replace, and update calls.

• name now accepts at most 100 characters (previously 500); message accepts at most 4,000 characters (previously 100,000). Shorten oversized values before submitting a write. Existing jobs remain readable.
• Agent-scheduled outbound targets require an explicit endpoint write grant both when scheduled and when fired; read access is insufficient.
• Manual runs, including Agent wakeups, consume the rolling daily fire limits. Agent-bound runs must fit both the owner and Agent limits.
• Re-enabling a firing job and overwriting a terminal run result return a conflict.

2026-09-01 - Bounded Workflow Trigger Chains

Compatibility: additive diagnostics with a tighter recursive-chain safety bound.

• A Workflow terminal event now counts as one trigger-chain hop. Existing three-hop recursive chains can therefore stop one Workflow transition earlier with chain_depth_exceeded; direct runs still start at depth zero.

2026-09-01 - Workflow Step Name Validation

Compatibility: validation is stricter for Workflow graph writes and activation.

• Workflow step names must now contain 1–64 ASCII letters, numbers, underscores, or hyphens. Invalid graphs return HTTP 422 with the explicit INVALID_STEP_NAME code and per-step details.
• Existing stored graphs remain readable, but invalid legacy step names must be renamed when the graph is next replaced and before it can be activated.
• Workflow templates now resolve nested trigger payload and prior-step output paths. Missing values retain the existing empty-rendering warning behavior.

2026-08-21 - Inline Audio and Video Delivery

Compatibility: browser behavior fix; response schemas are unchanged.

• Chat attachments, voice messages, and File Center previews now deliver the supported MP3, MP4, Ogg, WAV, and WebM audio/video MIME types without forcing Content-Disposition: attachment, so browser-native players can load them.
• Opening one of these audio/video file links in a new tab now uses the browser’s media player instead of immediately downloading the file. Other file types retain their existing download behavior, and active HTML, SVG, and XML formats retain hardened attachment delivery.

2026-08-20 - Managed Space Wager Sessions

Compatibility: additive APIs with retired gift-send surfaces.

• Added Space-scoped, short-lived OAuth client_credentials tokens with the wager scope and managed session open, read, heartbeat, lock, cancel, and partial/final settle endpoints under /api/v1/wager/sessions.
• Added a Web-session-only buy-in endpoint behind the native opaque-iframe arinova:wager-buyin-request bridge. Buy-ins accept paid and won API points, reject bonus points and Space owners, enforce authoritative version/range checks, stable idempotency, and a 1,000,000-point UTC daily cap.
• Added the non-withdrawable won pool and the wager_stake, wager_payout, wager_refund, and wager_rake ledger sources. Payout and creator rake are immediate; final settlement has no pending or dispute-window state.
• Added admin session inspection, force-void, settlement reversal, recovery shortfall anomalies, terminal-session reconciliation, expiry reaping, and active-table guards for refunds, downlisting, Space deletion, and owner purge.
• The v1 hand-history contract is disclosure plus evidence retention: creators retain game history, while Arinova preserves the exact reported settlement payload and immutable wallet evidence. Gameplay-level technical enforcement remains reserved for v2.
• Retired /api/gifts/send, /api/gifts/catalog, and the remaining v1 gift send path with 410; historical gift reports and leaderboards remain readable.

2026-08-11 - Managed Space Catalog Purchases and Subscriptions

Compatibility: additive APIs with a breaking retirement of unsafe free-amount charges.

• POST /api/v1/economy/purchase now returns 410 SPACE_ECONOMY_PURCHASE_RETIRED. Managed Spaces can no longer choose an amount or debit a player directly from an opaque iframe.
• Managed Spaces declare server-authoritative consumable, durable, or subscription products. Runtime reads are available at GET /api/v1/spaces/{spaceId}/products and inventory reads/consumes at /api/v1/spaces/{spaceId}/inventory.
• A runtime requests a purchase with the additive protocol-v1 arinova:purchase-request bridge message. The parent loads the catalog, displays a native confirmation, and calls the session-only catalog purchase endpoint. The result is returned as arinova:purchase-result.
• Every purchase and consume requires a stable idempotency key. Catalog prices are locked with expectedPricePoints; a changed price returns 409 SPACE_PRODUCT_PRICE_CHANGED.
• Space subscriptions renew every 30 days by default, support cancel, resume, and retry from the platform UI, and expose active, past_due, or ended state through inventory. Only the first period is refundable within one hour; renewals are not refundable.
• There is intentionally no daily spend cap. Each charge requires native user confirmation, while authenticated route rate limits remain the capacity control.
• POST /api/v1/agent/chat and /api/v1/agent/chat/stream now dispatch through the same Agent runtime and billing path as a normal conversation. An owned BYOA Agent uses its connected external runtime; an owned platform Agent performs the normal per-message point reservation, usage settlement, and creator revenue flow. The API no longer falls back to a platform-paid model call.
• If the selected Agent has no usable billing/runtime configuration, or a platform Agent cannot reserve enough points, both endpoints return HTTP 402 with { "error": { "code": "AGENT_BILLING_UNAVAILABLE", ... } } before dispatch. A streaming failure after SSE headers were sent is emitted as data: {"type":"error","error":{"code":"AGENT_BILLING_UNAVAILABLE"|"UPSTREAM_ERROR","message":"..."}}. Clients must treat this as terminal and must not interpret the connection close as a successful response.
• Agent usage generated through a managed Space records spaceId. Space API conversations are isolated from ambient memories, general-chat workers, attachments, tools, and actions; caller-supplied system-role content is handled as untrusted application context.

2026-08-05 - Mindmap Create-Side Placement

Compatibility: additive.

• POST /api/v1/mindmaps/{id}/nodes now accepts the optional layoutSide request field with auto, left, or right for direct children of the root node. Omitting the field preserves existing placement behavior.
• Supplying layoutSide below the first level, or supplying an unknown value, returns the existing v1_mindmaps_invalid_layout validation error. Response and WebSocket event schemas are unchanged; created nodes already expose layoutSide.

2026-07-28 - Office Caller Identity and Action Coverage

Compatibility: additive.

• Slides, Workbooks, Image Projects, and Workflows now have explicit session-only Web adapters and caller-aware API v1 adapters over their shared product operations. Existing user sessions and ari_cli_* CLI keys retain their response, error, version, event, cache, export, and workflow behavior.
• API v1 Agent-token support is additive. Every Agent resource operation is owner-scoped and requires the matching current direct or Space-derived product grant/role; ambiguous credentials and cross-owner grants fail closed. Mutations retain Agent attribution instead of impersonating the owner user.
• Added default-enabled owner-managed Agent create capabilities for Docs, Kanban boards, Calendars, Image Projects, and Workflows while preserving the existing Form, Mindmap, Slide deck, Workbook, and Notebook capabilities.
• Expanded the existing Office Action umbrellas with bounded container, lifecycle, export, Image Project, and Workflow operations. Historical flat Action names remain directly callable. Umbrella resolution now preserves the public action, selected sub-action, and resolved flat action in redacted audit metadata.
• High-impact operations retain user confirmation and current-policy revalidation. Dry runs remain free of product mutations, exports, events, billing, and queue dispatch; stable Action call IDs make retryable creates, revisions, exports, and Workflow runs idempotent.
• Added explicit user/Agent actor columns for Image Project document revisions through a forward-only migration. Existing user-created revision history is backfilled without changing public version identifiers.
• See Office surface compatibility and Office Action contract for the canonical identity, route, operation, and safety contracts.

2026-07-27 - Retired App-Secret Wallet Mutations

Compatibility: breaking security fix.

• POST /api/v1/economy/charge and POST /api/v1/economy/award now return 410 SERVER_ECONOMY_MUTATION_RETIRED without changing a wallet. App credentials alone cannot represent a user’s consent to a debit or a funded source for a credit.
• This migration path was superseded on 2026-08-11 by managed catalog products and the parent purchase bridge. Platform-funded credits remain available only through audited internal/admin wallet flows.

2026-07-26 - ChatGPT Conversation Export Memory Import

Compatibility: additive.

• Memory import now accepts official ChatGPT data-export ZIP files, conversations.json, and numbered conversations*.json files.
• Preview remains side-effect-free and returns conversation, text-message, and processing-chunk counts without transcript samples.
• Background extraction uses only user-authored statements as evidence; assistant messages are context only. Candidates still require review before write.
• ChatGPT uploads have a 50 MiB compressed limit plus bounded archive, extracted-size, conversation, message, and chunk limits. PDF, DOCX, and unrelated binary inputs remain unsupported.

2026-07-23 - File Center Storage Plans

Compatibility: additive.

• Added matching /api/file-storage/* and /api/v1/file-storage/* plan, subscription, tier-change, cancel, resume, and retry routes. Mutations use API points and require a visible-ASCII Idempotency-Key.
• POST /api/v1/workspaces/purchase now accepts optional tierUnits from 1 to 10 and returns storageSubscription; omission remains a tier-1 purchase.
• Paid storage units are now 15 GiB and 5,000 API points per 30-day cycle, up to 150 GiB. Personal usage reports the effective free or subscribed quota.
• Added auditable purchase, prorated-upgrade, and renewal wallet sources. Shared-space members do not receive owner billing details.
• See File Center Storage Subscriptions for lifecycle, migration, deployment, and rollback requirements.

2026-07-23 - Image Project Layer Documents

Compatibility: additive with a guarded behavior change.

• Added document reads, project-scoped layer/preview candidate uploads, and atomic revision commits under /api/v1/image-projects/{id}.
• Image Project and version payloads add documentRevision and hasLayerDocument without changing flattened version UUIDs or deep links.
• Existing projects and saved versions without a snapshot are returned as a deterministic single-raster V1 document and require no backfill.
• Revision commit requires a quoted If-Match, validates project-scoped managed assets, and is conflict-safe and idempotent.
• Current-image mutation through project PATCH now returns IMAGE_PROJECT_REVISION_REQUIRED; title rename remains supported. Clients must save an editable document plus flattened preview through the revision endpoint.
• The same typed handler graph remains mounted at the legacy Web prefix /api/image-projects for first-party compatibility.

2026-07-23 - Persistent Office Version History

Compatibility: additive.

• Added list/create/detail/restore/copy history routes for Workbook, Slide deck, Mindmap, and Forms under their existing /api/v1 resource namespaces.
• List routes use opaque cursor pagination; detail routes return bounded, product-specific previews and never raw compressed snapshots.
• Named creation and copy are idempotent. Restore requires expectedHeadVersionId and returns HISTORY_CONFLICT when the history head changed.
• Current edit-grade resource access is required. Agent callers additionally need a current write grant; public/share/responder tokens cannot read history.
• Workbook, Slide, and Mindmap restore in place after a mandatory pre-restore checkpoint. Form restore creates unpublished draft changes and does not change the live published revision or any response binding.
• Copy creates a new resource with canonical deep link and fresh version 1; source history and source permissions are not copied.

2026-07-19 - Creator Community Console Retired

Compatibility: breaking.

• Removed GET /api/v1/creator/community and its Web-only alias GET /api/creator/community. Community creation and management remain available through the dedicated /community product flow.
• Creator dashboard creation counts and revenue breakdowns no longer expose a community bucket. Historical creator-wallet rows for the retired paid community product are included in other.

2026-07-16 - Free, Resumable Memory Import

Compatibility: additive.

• Added side-effect-free POST /api/v1/memories/import/preview with the same multipart parser and validator as the start route.
• POST /api/v1/memories/import now accepts Idempotency-Key, returns isFree: true, and retains deprecated chargedPoints: 0 for compatibility. Memory import no longer checks or debits wallet balance.
• Added unfinished-import list, authorized status, discard, and retry lifecycle routes. Existing entry patch/delete, duplicate review, and confirm routes remain compatible.
• Added persisted source/format, correlation, idempotency, and sanitized failure metadata through a forward migration. Original files and file names are not retained.
• The arinova.memory.import_memories Action uses the same strict parser and permanent-free contract. Dry-run retains wouldChargePoints: 0; execute retains chargedPoints: 0.
• At launch, full ChatGPT archives and ZIP were unsupported; the additive 2026-07-26 adapter above supersedes that limitation. PDF, DOCX, and unrelated binary files remain unsupported.

2026-07-13 - Economy Idempotency Keys

Compatibility: additive.

• Added optional idempotencyKey to POST /api/v1/economy/charge, /award, and /purchase. Repeating a request with the same app/user-scoped key reuses the original wallet transaction instead of applying the balance mutation again.
• Calls that omit idempotencyKey retain the previous behavior during the compatibility window and emit a server warning; SDK and app-server callers should send a stable key for every retryable operation.

2026-07-13 - Copy Files into Shared Spaces

Compatibility: additive.

• Added POST /api/v1/files/{id}/copy ({ spaceId, folderId? }) to copy a personal file into a shared space as an independent file: new object, new row, attachment_id/conversation_id severed, provenance recorded in source_metadata.copiedFromFileId. Unlike /move, any source_type is eligible because the original stays in the personal library.
• The Web File Center now offers “Copy to space” everywhere it previously offered “Move to space”; POST /api/v1/files/{id}/move remains available for SDK/CLI ownership transfers with its existing source-linked restrictions.

2026-07-11 - Creator Agent Listings Retired

Compatibility: breaking.

• Removed GET /api/v1/creator/agents and its non-v1 alias GET /api/creator/agents after retiring user-authored Agent Hub listings.
• Creator API keys remain supported for stickers, themes, spaces, and other creator resources. External CLI clients must remove any creator-agent-listing command that called the retired endpoint.

2026-07-10 - Shared Space File Containers

Compatibility: additive.

• Added /api/v1/workspaces CLI/SDK endpoints for shared file workspaces, with matching /api/workspaces endpoints for the Web app. The existing spaces namespace remains dedicated to game/playground spaces.
• Added POST /api/v1/files/{id}/move for explicit personal/shared-space ownership transfers.
• Added PATCH /api/v1/files/{id} for display-name updates. The stored R2 key remains unchanged.
• Added optional spaceId to POST /api/v1/files/upload and the File Center folder endpoints; omitted values preserve the existing personal-library contract.
• Kept GET /api/v1/files personal-only. Shared-workspace files and virtual document items are returned only by /api/v1/workspaces/{id}/items.
• File download authorization now resolves tracked files rows through personal ownership or shared-space membership before considering legacy key rules.
• Shared-space deletion and deleted-owner retention now use a 30-day lifecycle; transferable spaces move to the earliest active admin, while ownerless spaces become read-only before cleanup.
• Shared-space mutations now fan out space_updated, member_changed, item_added, item_removed, and quota_changed events; DELETE /api/v1/files/{id} now supports role-checked shared-space files.
• POST /api/v1/workspaces now atomically consumes one shared-workspace entitlement and applies the SPACE_TIER_BYTES quota; missing entitlement still returns SPACE_ENTITLEMENT_REQUIRED.
• Shared-space item rows now include sourceType; file detail and URL-refresh endpoints accept active shared-space members while retaining their personal-file behavior.