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 2 March 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 five 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.¶

5. An optional read-only recipe surface, "GET /workflows", publishing named multi-step sequences of catalogue operations (Section 7).¶

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.6 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 "best" suffix is not currently registered in the Well-Known URIs registry (see IANA Considerations).¶

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

{
  "best": {
    "version": "0.9.6",
    "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 8). 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).¶

{
  "schema": "submit-order",
  "version": "1.0",
  "dataschema":
    "https://api.example.com/commands/submit-order/1.0",
  "description": "Submit a market order",
  "impact": {
    "categories": ["financial"],
    "confirmation": "required",
    "warning": "Places a real order on your broker account.
                Capital is at risk."
  }
}

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). Query catalogue entries and schema documents MAY carry the same "workflows" cross-link array as their command counterparts (Section 7). 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. Workflows

Workflows are published recipes: read-only, named sequences of catalogue operations with per-step guidance, for multi-step processes whose order is a fixed, well-known happy path. The capability ("io.best.agents.workflows") is optional and strictly descriptive: the service never executes, retries, tracks, or branches the steps; the caller -- typically an autonomous agent -- sends each operation itself and waits for its outcome before proceeding.¶

The index is deliberately shallow, so a consumer can hold the entire list in one read and choose; full recipes are fetched one at a time. Workflow identifiers are stable, service-defined, URL-path-safe strings (reverse-domain notation or kebab-case); renaming an identifier is a breaking change for anything linking to it.¶

Each step of a recipe carries "kind" ("command" or "query": whether the step is a "POST /commands" or a "GET /queries/{schema}"), "dataschema" (the resolvable URI of the operation's schema document in the service's live catalogue -- recipes reference the catalogue and never duplicate it, so they cannot drift from the real contracts), an optional "optional" flag (true when the step applies only in some runs), and optional "guidance" (how the step combines with the others: what to carry forward, what to wait for, when to skip).¶

GET /workflows/io.example.workflows.onboard-a-worker
{
  "id": "io.example.workflows.onboard-a-worker",
  "name": "Onboard a worker",
  "description": "Create the engagement, assign a contact, and
    invite the worker. Drive each step yourself and wait for its
    outcome before the next.",
  "steps": [
    { "kind": "command",
      "dataschema":
        "https://api.example.com/commands/submit-employee/1.0",
      "guidance": "Creates the engagement. Keep the correlationId
        -- every later step references it." },
    { "kind": "query",
      "dataschema":
        "https://api.example.com/queries/list-employees/1.0",
      "guidance": "Poll until the new engagement appears --
        commands are asynchronous." },
    { "kind": "command",
      "dataschema":
        "https://api.example.com/commands/invite-worker/1.0",
      "optional": true,
      "guidance": "Only when the user wants the invitation sent
        immediately." }
  ]
}

Cross-linking is the single discoverability mechanism: an operation advertises the recipes it belongs to through the "workflows" array -- the identifiers of the published workflows the operation participates in -- carried on its catalogue entry and on its schema document as a top-level member (JSON Schema tolerates unknown keywords; BEST names this one, and validators ignore it). Both surfaces carry the same array, so the pointer is present at whichever read a consumer performs before acting. Servers publishing workflows SHOULD stamp it in both places for every operation that appears in a recipe; consumers SHOULD fetch the referenced recipe before composing a multi-step sequence themselves. Human-readable descriptions are free to mention recipes, but the protocol attaches no discoverability role to prose.¶

The capability's boundary is deliberate: the moment a service executes, retries, persists, or branches steps on the caller's behalf, it has built an execution runtime, which is out of BEST's scope. Execution engines belong behind the service, not behind this capability.¶

8. 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.¶

9. 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 8.¶

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).¶

10. 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.¶

11. 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.¶

High-impact commands:

Commands that are destructive, irreversible, or bypass a compliance control SHOULD require a control beyond the submitting credential -- human approval, a second principal, or out-of-band confirmation -- and that control MUST NOT be self-serviceable by the submitting credential. Servers SHOULD declare the "impact" annotation (Section 4.2) on such commands so consumers can discover the obligation; the annotation is advisory to consumers and never substitutes for the server-side control.¶

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.¶

12. IANA Considerations

This document has no IANA actions.¶

The protocol uses the well-known URI path prefix "/.well-known/best" ([RFC8615]). The "best" suffix is not registered in the "Well-Known URIs" registry: a provisional registration was requested in August 2026 and declined by the designated expert, under the registry's policy that single common words and short terms are registrable only by recognised standards development organisations. The suffix is therefore used without registration. Registration in that registry serves collision avoidance rather than being a precondition for use; readers should nonetheless be aware that unregistered use carries a collision risk, mitigated in practice by the same policy preventing other registrants from claiming the suffix. The author intends to pursue registration again should this specification be adopted within the IETF.¶

This document establishes no new registries.¶

13. 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