AstrBot-Desktop/docs/protocol/v1/http.md

1.6 KiB

Desktop Gateway v1 HTTP and SSE surface

Public discovery

GET /desktop/v1/health
GET /desktop/v1/server-info
GET /desktop/v1/capabilities

server-info.serverInstanceId becomes the expected server identity for the active connection. A later mismatch freezes that connection rather than silently rebinding it.

Authentication

POST /desktop/v1/auth/login
POST /desktop/v1/auth/refresh

Credentials and returned tokens remain in the Rust layer. Request and response bodies containing credential material must not derive or use unrestricted debug logging.

Messaging and events

POST /desktop/v1/messages
GET  /desktop/v1/events/stream
POST /desktop/v1/events/{event_id}/ack

SSE frames carry both the SSE id and the complete JSON event envelope in data. Reconnect uses the Last-Event-ID request header. Replay and de-duplication are scoped to the local connection profile, so the same event ID on two server instances remains two distinct events.

Initial event types:

system.heartbeat
message.delta
message.completed
message.proactive
agent.status
tool.proposal
capabilities.changed
error

Local action reporting

POST /desktop/v1/local-actions/{action_id}/accepted
POST /desktop/v1/local-actions/{action_id}/rejected
POST /desktop/v1/local-actions/{action_id}/progress
POST /desktop/v1/local-actions/{action_id}/result

A tool.proposal is only an untrusted proposal. Schema validation, tool registry validation, slot/profile checks, server identity verification, expiry checks, local policy, and user authorization happen before any local execution.