Building applications
APIs and protocols
Shared application services, REST requirements, MCP schemas, runtime commands, and webhooks.
v1 design baseline. This page specifies intended behavior. Delivery and validation are tracked in the implementation plan; it is not a claim that the platform is already implemented.
Interfaces
Filament UI
REST/OpenAPI
MCP
future CLI
runtime-agent protocol
webhooks
All human-facing interfaces use the same command/query layer.
REST
Versioned API:
/api/v1/organizations/{org}/apps
/api/v1/organizations/{org}/builds
/api/v1/organizations/{org}/deployments
/api/v1/organizations/{org}/security/ip-lists
Requirements:
- OpenAPI contract
- Idempotency key for creates/actions
- Cursor pagination
- Optimistic locking/ETags
- Stable error codes
- Correlation IDs
- Explicit tenant context
- Fine-grained OAuth scopes
- No silent cross-org fallback
MCP
MCP operations call the REST/application-service layer internally.
The model does not gain special permissions merely because it uses MCP.
Tool annotations mark:
- Read-only
- Destructive
- Open-world/network activity
These annotations help the client UX but do not replace server-side authorization. OpenAI explicitly notes that such annotations are not authorization controls. OpenAI security and privacy guidance
Runtime protocol
The runtime agent uses:
- mTLS workload identity
- Cluster-specific certificate
- Versioned protocol
- Outbound connection
- Command IDs
- Sequence/reconciliation version
- Acknowledgements
- Desired-state hash
- Health/capacity reporting
A cluster may act only for organizations/environments explicitly assigned to it.
Webhooks
External Git and future integrations use:
- Signature verification
- Replay protection
- Delivery ID deduplication
- Timestamp tolerance
- Minimal permissions
- Audit event
- Asynchronous processing