Records a new draft generation of a protocol binding spec.

POST

/v1/m/sessions/protocol-binding-specs

curl --request POST \
  --url 'https://example.com/v1/m/sessions/protocol-binding-specs?mode=validate' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "binding_key": "example", "currency_policy": "pinned", "direction": "inbound", "generation": 1, "known_losses": [ { "acceptance_ref": "example", "accepted": false, "field": "example", "reason_code": "example" } ], "local_kind": "work_item", "local_selector": {}, "mapping": [ { "cardinality": "one_to_one", "source": "example", "target": "example", "transform": "identity" } ], "mapping_schema": "example", "peer_authority": "example", "permission_profile_ref": "example", "protocol": "a2a", "protocol_version": "example", "remote_resource_kind": "example", "remote_resource_ref": "example", "rule_refs": [ "example" ], "supersedes_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

• this engine

Records a new draft generation of a protocol binding spec. Two properties are load-bearing and deliberate.

Authorizations

• bearerAuth

Parameters

Header Parameters

X-Olivares-Tenant

string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Idempotency-Key

string format: uuid

Canonical UUID required when mode=apply; reuse it only for an exact retry.

If-Plan-Hash

string

/^(sha256:)?[0-9A-Fa-f]{64}$/

SHA-256 plan hash required when mode=apply; apply must reproduce it. For state transitions it must agree with body.plan_hash when both are supplied.

Query Parameters

mode

required

string

Allowed values: validate plan apply

Mandatory authoring phase. The server derives a fresh capability witness; validate and plan are observational, while apply revalidates and commits the spec transition.

Request Body ^required

Media type application/json

Closed ProtocolBindingSpecInput for exactly one immutable, version-pinned protocol mapping generation.

object

binding_key

required

string

>= 1 characters <= 128 characters

currency_policy

required

string

Allowed values: pinned

direction

required

string

Allowed values: inbound outbound bidirectional

generation

required

integer format: int64

>= 1

known_losses

Array<object>

<= 128 items

object

acceptance_ref

Required when accepted=true and rejected when accepted=false.

string

>= 1 characters <= 512 characters

accepted

Whether the semantic loss has an explicit acceptance witness.

boolean

field

required

Field whose semantics are not preserved by the mapping.

string

>= 1 characters <= 512 characters

reason_code

required

string

>= 1 characters <= 128 characters

local_kind

required

string

Allowed values: work_item agent model channel

local_selector

required

Canonicalizable JSON object selecting the local surface; encoded size is limited to 64 KiB.

object

key

additional properties

any

mapping

required

Array<object>

>= 1 items <= 128 items

object

cardinality

required

string

Allowed values: one_to_one one_to_many many_to_one

source

required

Exact local field or projection reference.

string

>= 1 characters <= 512 characters

target

required

Exact remote field or projection reference.

string

>= 1 characters <= 512 characters

transform

required

string

Allowed values: identity text reference metadata status

mapping_schema

required

string

>= 1 characters <= 128 characters

peer_authority

required

Peer authority or normalized absolute authority URL.

string

>= 1 characters <= 512 characters

permission_profile_ref

required

Pinned permission-profile reference.

string

>= 1 characters <= 512 characters

protocol

required

string

Allowed values: a2a mcp

protocol_version

required

Pinned protocol version; latest, current and * are rejected.

string

>= 1 characters <= 512 characters

remote_resource_kind

required

string

>= 1 characters <= 128 characters

remote_resource_ref

required

Opaque remote resource reference.

string

>= 1 characters <= 512 characters

rule_refs

Array<string>

<= 64 items unique items

supersedes_id

string format: uuid

/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/

validation

Server-derived capability witness. Any client-supplied value is ignored; omit this property. Activation requires a fresh CLEAN witness with a non-empty observed_at.

object

code

required

string

>= 1 characters <= 128 characters

observed_at

string format: date-time

verdict

required

string

Allowed values: CLEAN BROKEN UNKNOWN

workspace_id

required

string format: uuid

/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/

Responses

200

OK

Media type application/json

object

Example ^generated

{}

201

ProtocolBindingSpec draft created

Media type application/json

object

Example ^generated

{}

400

Bad request

Media type application/json

object

Example ^generated

{}

401

Unauthenticated

Media type application/json

object

Example ^generated

{}

403

Forbidden

Media type application/json

object

Example ^generated

{}

404

Not found

Media type application/json

object

Example ^generated

{}

409

Conflict / setup required

Media type application/json

object

Example ^generated

{}

412

ETag or plan precondition failed

Media type application/json

object

Example ^generated

{}

428

Apply precondition required

Media type application/json

object

Example ^generated

{}

429

Rate limited

Media type application/json

object

Example ^generated

{}

503

Required store is unavailable

Media type application/json

object

Example ^generated

{}