Contracts

Three JSON shapes define the ShoulderTap protocol: ContextRequest (a consumer asking for context), ContextProposal (an expert’s answer), and ConsumerRegistration (how a consumer signs up). The authoritative JSON Schemas live in spec/schemas/*.json in the repository, generated directly from the reference implementation and checked for drift.

ContextRequest

A consumer’s request for context. Four fields are required: kind, topic, question, consumer.

string

ULID, prefix req_. Engine-assigned if omitted.

org_id

string

default:"default"

Fixed to "default" in the single-tenant community edition.

kind

string

required

The question kind; determines the answer’s capture schema and which consumers it routes back to. See Kinds.

topic

string

required

The routing key. Normalized to lowercase for matching against expert topics.

question

string

required

The raw question.

context

object

Free-form, shown to the expert. context.asked_because becomes the “why I’m asking” line in the ask.

target_experts

array | null

default:"null"

[{ expert_id, role }]. Bypasses topic routing entirely and asks these experts directly. role defaults to "primary".

routing_policy

object

Per-request overrides for the config defaults.

Show fields

primary_experts

array

escalation_targets

array

escalation_after

string | null

default:"null"

ISO-8601 duration, for example "PT2H". Falls back to defaults.escalation_after.

give_up_after

string | null

default:"null"

ISO-8601 duration. Falls back to defaults.give_up_after.

priority

integer

default:"50"

consumer

string

required

The submitting consumer’s id.

dedup_key

string | null

default:"null"

Requests with the same key from the same consumer, within the dedup window, are deduplicated. See Concepts.

correlation

object | null

default:"null"

Free-form passthrough, for example { "trace_id": "..." }.

created_at

string

ISO-8601 date-time.

Example

{
  "kind": "glossary.definition",
  "topic": "revenue metrics",
  "question": "What does 'active customer' mean for Q2 reporting?",
  "consumer": "bi.assistant",
  "context": {
    "asked_because": "BI agent hit low confidence answering a user query",
    "entity": "dim_customers.active_flag"
  },
  "dedup_key": "glossary:dim_customers.active_flag"
}

ContextProposal

An expert’s answer, structured and attributed. Required: request_id, kind, answer, provenance, consumer.

string

ULID, prefix prop_. Engine-assigned.

request_id

string

required

The request this answers.

kind

string

required

Mirrors the request’s kind.

answer

string

required

The expert’s verbatim reply. Never dropped, even if structuring fails.

structured

object | null

default:"null"

The LLM-structured form of the answer, matching the kind’s schema. null on extraction failure or when confidence is below 0.3.

confidence

number | null

default:"null"

The structurer’s self-assessed extraction confidence, independent of whether structured ended up null.

provenance

object

required

Who answered and how.

Show fields

expert_id

string

required

expert_name

string

required

answered_via

string

required

The transport that carried the answer, for example slack.

answered_at

string

required

ISO-8601 date-time.

slack_thread_ts

string | null

default:"null"

escalated

boolean

default:"false"

consumer

string

required

created_at

string

ISO-8601 date-time.

ConsumerRegistration

How a consumer registers to receive answers. Required: id, handles_kinds, delivery.

string

required

The consumer’s id, for example bi.assistant.

handles_kinds

array

required

The kinds this consumer deals with.

delivery

object

required

A discriminated union on type: { "type": "webhook", "url": "..." } or { "type": "inprocess" } for an SDK-embedded consumer.

dedup_window

string

default:"P1D"

ISO-8601 duration for the deduplication window (default one day).

auto_accept

boolean

default:"false"

Deliver proposals without human review. Off by default — see the warning in Consumers.

kind_schemas

object

Optional map of kind name to a custom JSON Schema, overriding the built-in for that kind. See Kinds.

Overview

Endpoints

Contracts

ContextRequest

Example

ContextProposal

ConsumerRegistration

​ContextRequest

​Example

​ContextProposal

​ConsumerRegistration

ContextRequest

Example

ContextProposal

ConsumerRegistration