# Extension HTTP behavior This reference describes caller-visible behavior for selected extension services. It is not an exhaustive extension inventory. [OpenAPI](openapi.yaml) defines supported routes and schemas. [HTTP API behavior](http-api-design.md) defines common HTTP rules. Extension management stays under `/extensions/{extension_name}`. These routes are not aliases for core commands. The extension owns validation, persistence, permissions, and typed domain results. Enabled routes and action descriptors are discoverable through the server and session catalog. HTTP bearer clients are human operators. Internal model callers use the same domain operations with trusted caller context supplied by the runtime. A JSON `role`, `caller`, or session ID cannot grant human permission. Core shutdown and global credential management cannot be delegated through a page descriptor. Disabling a service returns `404` for its HTTP routes. Extension lists use common pagination and may include optional `page` and `glance` render hints. Each editable row includes `resource`, containing URL, value, and its observed `etag`. Work, paperclip, and schedule item reads are canonical item representations. Hook and linked-group reads include runtime observations and expose a separate `view=configuration` resource for edits, using the session configuration convention. Its validator covers only the complete configuration representation, not changing runtime observations. Mutation responses contain `resource` and `notification`. Notification has `state: "not_requested"|"queued"|"failed"`, with nullable safe `code` and `detail`. Multiple targets use `notifications`, one result per target. Creates return `201` with `Location`. Edits return `200`. Deletes return `200` when reporting a deleted resource or notification outcome, otherwise `204`. A committed ledger edit remains successful if notifying an agent fails. Secret-generating POSTs have no automatic retry after response loss. The caller reads the resource and explicitly rotates if the secret was lost. ## Work Work operations are scoped by the invoking workspace's linked group. The creation workspace and parent are immutable after creation. Deletion refuses an item with children. Item edits and deletion use the observed `If-Match`. The [work service](../src/albedo/harness/extensions/work/service.gleam) owns these operations. OpenAPI defines writable fields, state variants, and text bounds. Human mutations can name `notify_session_id` to queue the existing user-change note. Results distinguish ledger commit from note delivery. Models retain their workspace-scoped create, read, update, and delete operations through trusted internal bindings. Work pages preserve linked-workspace labels and pending-work glances. The CLI accepts `/work add `, `/work edit <id> <title>`, `/work status <id> <status>`, and `/work remove <id>` alongside page forms. These shortcuts invoke the page's declared HTTP actions. Removal asks for confirmation. Targeted shortcuts fetch the item even when it is outside the first list page and retain its ETag through confirmation. ## Paperclips The paperclip ledger is global. The original topic, title, message, suggestion, and origin remain immutable. Human review can acknowledge, reply to, resolve, dismiss, or delete an item under its observed validator. [Paperclips](../robot-docs/paperclips.md) and the [service implementation](../src/albedo/harness/extensions/paperclips/service.gleam) describe the owners. OpenAPI defines the request and resource fields. Humans PATCH status to `acknowledged`, `resolved`, or `dismissed`, or supply `reply`. A reply acknowledges the item and attempts a note to its filing session. The reply stays saved when notification fails. DELETE removes the item. PATCH with reply cannot also set resolved or dismissed. Human resolution can include a resolution note. It never changes the original message. A model's resolving session comes from trusted runtime context. DELETE requires `If-Match`. Models can file, list, and resolve still-open or acknowledged items with a nonempty resolution. Human terminal decisions cannot be overwritten by a model. All edits use `If-Match`. Listings use newest-first cursor order and global glances. The CLI accepts `/paperclips acknowledge <id>`, `/paperclips reply <id> <text>`, `/paperclips resolve <id> [note]`, `/paperclips dismiss <id>`, and `/paperclips remove <id>` through the same declared actions as page forms. Removal asks for confirmation. A stale ETag returns a conflict without retrying the mutation. ## Web search The global provider order controls which web-search providers the model tries. It lives in `extensions.json`. Items carry name, label, 1-based position, and whether the provider is tried. POST takes `{"change": "up" | "down" | "toggle"}`. A move past either end leaves the order unchanged. An unknown name is 404. ## Schedule Scheduling is session-scoped. Once jobs cannot repeat. Recurring jobs and heartbeats require a repetition interval. Item patches and deletion use the observed `If-Match`. A prompt-only edit preserves the next delivery time. Changing the delay resolves the next time from commit time. OpenAPI defines the fields and interval bounds. The [schedule service](../src/albedo/harness/extensions/schedule/service.gleam) owns validation and updates. Once jobs disappear after durable delivery. Recurring prompts queue behind running work. Heartbeats skip busy sessions. Restart resumes the schedule without replaying every missed interval. Session deletion removes its jobs. ## Linked workspaces GET requires `workspace` and returns its complete group with bounded remote presence facts, paged where necessary. Configuration view contains membership and revision without remote presence facts. POST uses that observed configuration URL and its `If-Match`, with `other_workspace` and `other_etag` from the other group's configuration read. It checks both groups and merges them in one owner commit. Stale membership on either side returns `412`. DELETE uses the configuration URL plus `member` and checks that member belongs to the observed group at commit. The member becomes its own group. Neither operation deletes work or memory. Writes are human-only. Notifications to affected open sessions are reported separately from the committed group change. `notification_count` covers all targets. The response includes up to 200 outcomes and `truncated` when the list reaches its count or byte bound. ## Webhooks A hook targets one session. Its target is immutable. Editable configuration has a separate validator from changing delivery observations. Creation and rotation return a secret only in that operation response. Stored secrets do not appear in ordinary reads, logs, or SSE. Rotation and configuration changes use the observed `If-Match`. OpenAPI defines configuration fields, input bounds, and secret-generation requests. [Webhooks](../robot-docs/webhooks.md) links the signature and delivery owners. Permission reads return false when no setting exists. PATCH accepts explicit `agent_manage`, with omission retaining its value. Only humans grant it. Agent management remains restricted to that agent's target session. Turning management off does not disable hooks or prevent reading that session's own accepted delivery payloads. Hook edits use the caller's observed revision, not a revision fetched just before overwriting a stale screen. Incoming delivery POST has a 65,536-byte raw-body limit. It requires the configured HMAC-SHA256 signature and never accepts a bearer token instead. Default header is `X-Albedo-Signature` and prefix is `sha256=`. Missing or invalid signatures return `403`, without a daemon bearer challenge. Optional `X-Albedo-Event-Id`, at most 128 bytes without newlines, deduplicates by hook, ID, and body hash. A changed body under that ID returns `409`. Acceptance stores the delivery and its durable inbox entry together, then returns `202` with `delivery_id`. A full target inbox returns `429`. Unknown or disabled hooks return `404`. The pending bound is 1,000 per session. Delivery lists accept `state=pending|delivered|all`, default all, and common pagination. Metadata contains ID, hook ID, target session, receipt and delivery timestamps, attempts, and latest deferral reason. Direct delivery reads add `payload: { "encoding": "utf8"|"base64", "data": ... }`. Both direct and by-hook historical reads remain available after hook deletion. Payloads are external data and carry no instruction authority. Deleting a hook retains accepted deliveries. Deleting the target session removes its hooks and inbox. An operator exposing intake through a reverse proxy allows only the signed POST method, not management GET on the same path. ## OpenAI proxy The optional proxy uses an OpenAI-compatible envelope, including JSON and streaming responses. It is stateless with respect to agent sessions: the caller supplies history. Its format and body bounds override platform conventions for those routes. The supported request subset and provider translation belong to [the proxy contract](../robot-docs/proxy.md#translation) and the [proxy implementation](../src/albedo/harness/extensions/proxy/extension.gleam). User images must be base64 data URLs. Remote image URLs are not fetched. Unsupported fields return a proxy-format error. Text and reasoning stream as `delta.content` and `delta.reasoning_content`. Complete tool calls publish when the turn ends. Provider failure sends an error chunk before termination, or a JSON error for a nonstreaming request. The proxy uses daemon bearer authentication. An operator may explicitly enable anonymous loopback access. That policy never grants access to core or other extension routes. ## Related guides - [API overview](http-api-design.md) - [Session lifecycle and recovery](http-sessions.md) - [HTTP streams and recovery](http-streams.md) - [Change the HTTP API](contributing-api.md)