BEST: The Behavioral State Protocol

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 25 February 2027.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶

Table of Contents

1. Introduction

When an organisation operates multiple autonomous callers -- AI agents, process managers, integrations -- against heterogeneous systems, each pairing of caller and system tends to require a bespoke integration: the caller must be told, out of band, which operations the system accepts, what the payloads look like, how results are delivered, and how to associate a result with the request that caused it.¶

Command Query Responsibility Segregation (CQRS) provides the underlying semantics BEST builds on: writes are expressed as commands, and the results of processing are recorded as events. What CQRS does not provide is a common, machine-readable way for a caller to discover a service's command surface, observe its events, and correlate outcomes, without reading documentation or source code.¶

BEST fills this gap with four elements:¶

1. A discovery manifest at the well-known URI "/.well-known/best" describing the service's capabilities, transports, and authentication requirements.¶

2. A single command-ingestion entry point, "POST /commands", routed by the message "type" attribute rather than by URL structure.¶

3. A queryable event log, "GET /events", plus optional push delivery, through which the immutable facts produced by processing are observed; a first-class correlation identifier ties each event to the command that caused it.¶

4. An optional synchronous read surface, "GET /queries/{schema}", for reading current state before issuing a command.¶

BEST is deliberately not REST: there are no resources to manipulate and no CRUD verb semantics. Callers invoke named operations (commands such as "ProposeCounter" or "SubmitOrder") and observe the facts that result (events such as "CounterProposed"). Resource-oriented endpoints remain valid parts of a service's own API but are outside BEST's scope.¶

The protocol's design principles are: protocol-first (the specification defines the surface; implementations derive from it); compose, don't invent (the envelope is a CloudEvents profile [CLOUDEVENTS], contracts are JSON Schema [JSONSCHEMA], discovery uses a well-known URI [RFC8615], tenancy uses URI templates [RFC6570]); discoverable by default; transport-agnostic; modular (implementers expose only the capabilities they support); and implementation-agnostic (no prescribed language, framework, storage, or execution model -- a BEST service can equally be an AI agent, a deterministic backend, a sensor, or a human-operated workflow).¶

This document specifies the protocol as released in version 0.9.2 of the living specification [BESTSPEC].¶

2. Message Envelope

BEST messages are CloudEvents [CLOUDEVENTS]: every valid BEST message is a valid CloudEvents 1.0 message, so CloudEvents SDKs, brokers, and validators process BEST traffic unchanged. BEST is a profile that restricts and extends the envelope as follows: the "type" attribute MUST be PascalCase; "datacontenttype" MUST be "application/json"; "dataschema" MUST be present on commands (it MAY be absent on events, which are then untyped); one extension attribute, "correlationid", is defined; and consumers MUST ignore unknown envelope attributes rather than reject messages carrying them.¶

An example command and the event its processing produced:¶

{
  "specversion": "1.0",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source": "https://pm.example.com/negotiation-agent",
  "type": "ProposeCounter",
  "datacontenttype": "application/json",
  "dataschema":
    "https://api.example.com/commands/propose-counter/1.0",
  "time": "2025-07-01T10:30:00Z",
  "data": { "salary": 100000, "startDate": "2025-09-01" }
}

{
  "specversion": "1.0",
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "source": "https://api.example.com/negotiation",
  "type": "CounterProposed",
  "datacontenttype": "application/json",
  "dataschema":
    "https://api.example.com/events/counter-proposed/1.0",
  "correlationid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "time": "2025-07-01T10:30:01Z",
  "data": { "salary": 100000, "startDate": "2025-09-01",
            "contractId": "contract-42" }
}

3. Discovery

Every BEST endpoint serves a manifest at the well-known URI "/.well-known/best" ([RFC8615]) with media type "application/json", over HTTPS. This resource MUST be retrievable without authentication; every other endpoint MAY require the credentials declared in the manifest's "authentication" object. The path is canonical; consumers MUST NOT assume a ".json" file extension.¶

The manifest root is a single "best" object:¶

{
  "best": {
    "version": "0.9.2",
    "authentication": { ... },
    "tenants": { ... },
    "services": { ... },
    "capabilities": [ ... ],
    "agents": [ ... ]
  }
}

version (required):

The protocol version implemented, as MAJOR.MINOR.PATCH.¶

services (required):

An object mapping service keys to service definitions. Each service declares "version" and "description" and one or more transport bindings: "http" (the baseline -- its "endpoint" is the consumer-facing base URL to which all capability paths are appended) and optionally "mcp" (see Section 7). Multiple transports expose the same capability surface; they are alternative access methods, never separate operation sets.¶

capabilities (required):

An array of capability entries. Each carries "name" (reverse-domain identifier), "version", "description", "spec" and "schema" URLs (required for "io.best." capabilities; optional for custom ones), an optional "service" key naming the implementing service when the capability name prefix does not match it, an optional machine-readable "endpoints" array of { method, path } pairs appended to the service's "http.endpoint", an optional "status", and -- on the events capability -- an optional "push" object declaring supported push channels ("sse", "mcp").¶

authentication (optional):

Credential requirements for every endpoint other than the manifest itself: "type" ("none", "bearer", "apiKey", or "oauth2") plus, per type, "scheme", "in", "scopes", "tokenUrl", and a "docs" URL. Consumers MUST read this object before calling any other endpoint. Hosts requiring credentials SHOULD set "docs" to an onboarding page.¶

tenants (optional):

Multi-tenant discovery (see Section 3.1).¶

agents (optional):

A snapshot of service descriptors hosted by the endpoint: each descriptor carries "id", "name", "accepts" and "produces" (PascalCase event type strings), "status" ("running", "paused", "stopped", or "error"), and optional opaque "metadata". This array is a discovery hint, not a live directory; BEST defines no registry endpoint. Implementations that manage services dynamically expose that as an ordinary domain (commands and queries) under their own namespace.¶

Capability status semantics: "active" (the default) means every required endpoint exists and is callable; declaring "active" while returning 404 or 501 on a required route is a conformance violation. "partial" means a subset is implemented, which MUST be documented in the "endpoints" array. "planned" means nothing is callable yet.¶

Individual command types are domain data, not capabilities: a specific type such as "ProposeCounter" MUST NOT appear as a manifest capability entry. The capability declares the command surface; the types are discovered at runtime via "GET /commands".¶

"tenants": {
  "manifest": "https://api.example.com/.well-known/best/{tenantId}"
}

4. Commands

Commands are intents to change a domain service. The service validates, queues, and processes them asynchronously; results surface as events (Section 5).¶

POST /commands                    -> 201 { "id": "abc123",
                                          "correlationId": "abc123" }
GET  /events?correlationId=abc123        -> what has already happened
GET  /events/stream?correlationId=abc123 -> what happens next (push)

5. Events

Events are immutable facts published as the result of processing.¶

"GET /events" and "GET /events/stream" are complementary: a caller loads history first, then opens the stream.¶

An event with "dataschema" is typed: consumers can fetch the schema and validate. Without it, the event is untyped and the consumer interprets "data"; the envelope ("type", "source", "id", "correlationid", "time") still supports routing and correlation. Both patterns can coexist in one service.¶

BEST makes no replay guarantee: "GET /events" returns whatever the server currently exposes -- a full log, a recent window, or a view of domain records mapped to the event shape at query time. Clients MUST NOT assume completeness, ordering, or replay fidelity. For reliable point-in-time delivery, callers use a push channel.¶

6. Queries

Queries are synchronous reads of current state -- the read-before-write complement to commands (for example, an agent lists broker accounts before referencing one in a command). The capability is optional and declared in the manifest like any other.¶

The query schema document has up to three sections: "description", "parameters" (a JSON Schema for accepted query-string parameters, omitted when the query takes none), and "response" (a JSON Schema for the result body; required). Execution returns 400 for missing or invalid parameters and 404 for an unknown schema name.¶

Queries are not a query language (no filter expressions, joins, or aggregations), not a REST resource hierarchy (no per-item paths), and not event sourcing (they return current state as the service projects it; historical facts live in "GET /events").¶

7. Transports

HTTP is the baseline transport: every conformant service exposes it. All requests and responses are "application/json" (schema documents are "application/schema+json"; the event stream is "text/event-stream").¶

Every capability path is appended to the service's "http.endpoint"; the leading slash is a separator, not a root-relative indicator. For example, with "http.endpoint" of "https://api.example.com/tenants/acme", the path "/commands" resolves to "https://api.example.com/tenants/acme/commands". The "http.endpoint" value MUST be the consumer-facing public address, never an internal backend or service-mesh URL.¶

Authentication follows the manifest's "authentication" object: "bearer" maps to "Authorization: Bearer" credentials; "apiKey" to a header or query parameter named by the declaration. Every endpoint except "GET /.well-known/best" requires credentials when they are declared.¶

All error responses use a consistent body:¶

{ "error": { "code": "SCHEMA_NOT_FOUND",
             "message": "Unknown command schema 'foo'",
             "details": {} } }

A Model Context Protocol [MCP] binding MAY additionally be declared in a service's "mcp" transport object ("transport", "server", optional "push" and a transport-scoped "authentication" object). Every MCP tool wraps exactly one HTTP endpoint; the binding exposes the same logical capability surface to LLM tooling that cannot call HTTP APIs directly. When "push" is true, the server MAY deliver events as MCP server-to-client notifications, matched by correlation identifier.¶

8. Conformance

A BEST-compliant endpoint MUST:¶

1. Expose "GET /.well-known/best" returning a valid manifest: status 200, publicly retrievable, "application/json".¶

2. Include at least one service in the manifest.¶

3. List all supported capabilities with valid schema URLs.¶

4. Implement the HTTP surface for every listed capability.¶

5. Return valid JSON conforming to the referenced schemas.¶

6. Use the status codes and error format of Section 7.¶

7. Declare authentication in the manifest, or omit the declaration for public endpoints; an undocumented 401 is non-conformant.¶

Per-capability required endpoints, for capabilities declared "active" ("partial" capabilities are exempt but MUST document their available routes in "endpoints"):¶

Multi-tenant root manifests additionally follow the rules of Section 3.1.¶

Conformance does not require any specific language, framework, or architecture; any specific event transport; MCP support; or AI capabilities -- a BEST service can be deterministic or human-operated.¶

Versioning is semantic (MAJOR.MINOR.PATCH) at the manifest root, per service, and per capability. Consumers MUST ignore unknown fields for forward compatibility. All BEST identifiers use reverse-domain notation; the "io.best." prefix is reserved for this specification.¶

This document establishes no new IANA registries (see IANA Considerations).¶

9. Implementation Status

This section records the implementation status at the time of writing, per [RFC7942]; it is to be removed by the RFC Editor before publication.¶

Two production deployments of BEST exist -- dotquant.io (fintech trading platform) and remundo.com (business platform) -- implemented as separate codebases by the specification's author, each exposing discovery, commands, events, and queries over the HTTP binding. A generic reference MCP server (@behavioralstate/best-mcp, npm) adapts any BEST endpoint for MCP-capable LLM clients, and a conformance validator (@behavioralstate/best-validate, npm) executes this document's conformance checklist against a live endpoint. No implementation independent of the specification author is known yet.¶

10. Security Considerations

TLS:

Production endpoints MUST be served over HTTPS; MCP transports MUST provide TLS-equivalent confidentiality. Clients MUST validate certificates and MUST NOT send credentials over insecure transports.¶

Authentication surface:

"GET /.well-known/best" is the only endpoint defined as unauthenticated. "GET /events" MUST require authentication and tenant-scoped authorisation unless a stream is explicitly designated public. Distinct read and write scopes are RECOMMENDED. Because "POST /commands" is a single endpoint through which every named operation is invoked, coarse scopes are insufficient on their own: servers SHOULD enforce per-command authorisation policies per credential, evaluated deny-by-default on every submission.¶

Schema-selection SSRF:

Servers select validation schemas from their own catalogue, keyed by a server-owned identifier. Servers MUST NOT fetch a caller-supplied "dataschema" URI: a caller-controlled fetch is a server-side request forgery vector. Servers SHOULD reject commands whose "dataschema" does not match a catalogue entry.¶

Replay protection:

The envelope "id" is an idempotency key. Servers MUST reject duplicates within a retention window, scoped to the authenticated tenant or sender; a reused "id" with a different payload MUST return 409.¶

Untrusted "source":

The "source" attribute is caller-declared. Servers MUST NOT grant permissions or make security decisions from it, and SHOULD either overwrite it with the verified principal for audit purposes or record both values. Payload fields naming a principal likewise carry no authority.¶

Tenant isolation:

Tenant context MUST derive from authenticated identity, never from caller-supplied paths, parameters, or payload fields. Caches, deduplication stores, and event streams MUST be isolated per tenant; knowledge of another tenant's identifier grants nothing.¶

Input limits:

Servers MUST bound request body size (returning 413), JSON nesting depth, collection sizes, string lengths, and attribute counts, and SHOULD rate-limit per authenticated client and per tenant.¶

Manifest content:

The manifest is publicly retrievable by design. Its content MUST be limited to information intended for unauthenticated disclosure: no internal addresses, credential material, or sensitive integration names.¶

Credential passthrough:

Intermediaries such as MCP servers or gateways forward caller credentials. Passthrough MUST be opt-in per connection and off by default, credentials MUST be forwarded only to the configured endpoint and never logged, explicit per-request credentials take precedence over ambient ones, and multi-user intermediaries SHOULD fail closed.¶

11. IANA Considerations

IANA is requested to update the existing provisional registration of the "best" well-known URI suffix in the "Well-Known URIs" registry [RFC8615] to permanent, with this document as the specification reference:¶

URI suffix:

best¶

Change controller:

Riccardo Di Nuzzo (riccardo@dinuzzo.it)¶

Specification document:

this document¶

Status:

permanent¶

This document establishes no new registries.¶

12. References

Acknowledgments

The BEST envelope is a profile of CloudEvents, and the protocol's discovery model follows the well-known URI convention of RFC 8615; the author thanks the communities behind both. Feedback from the operators of the early production deployments shaped the correlation, multi-tenancy, and authorisation requirements in this document.¶

Author's Address