# 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 `,
`/work status `, and `/work remove ` 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 `, `/paperclips reply `,
`/paperclips resolve [note]`, `/paperclips dismiss `, and
`/paperclips remove ` 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)