Schemas

CalendarQuoteRequest

request_id

Uuid · uuid · required

CalendarQuote

calendar_href

string | null · required

/dav/cal/<account>/agent on the calendar store; null for delegated_google (#5340: the Google calendar is chosen after the admin's consent).

provider

string · enum · required

Enum values:

managed

delegated_google

available

boolean · required

display_name

string · required

reason

string · enum

provider_not_orderable is no longer answered (#5340 orders delegated_google); it stays for requests recorded before.

Enum values:

calendar_limit_reached

unknown_avatar

unknown_owner

unknown_external_agent

payment_not_confirmed

provider_not_orderable

unknown_provider

store_unconfigured

CalendarApproveRequest

requestId

Uuid · uuid · required

action

string · enum · required

Enum values:

approve

cancel

CalendarStatusRequest

organization_id

Uuid · uuid · required

avatar_type

string · required

A roster avatar type, or an external agent's subject agent:<uuid>.

CalendarStatus

state

string · enum

Enum values:

reserved

provisioning

active

releasing

failed

provider

string · enum

Enum values:

managed

delegated_google

calendar_href

string | null

ready

boolean

object

last_error

string | null

CalendarPassRequest

LapseSummary

examined

integer

graceStarted

integer

graceCleared

integer

released

integer

failed

integer

ProjectorSummary

calendars

integer

examined

integer

projected

integer

failed

integer

conflicts

integer

calendarFailures

integer

Instant

string · date-time

ISO 8601 instant with an offset.

ProjectionState

string · enum

Enum values:

pending

projected

failed

conflict

Where the booking stands on the agent's CalDAV calendar (ADR-003): conflict means the event was changed or deleted there by someone else; the booking still holds and the event is not overwritten until reviewed.

Booking

id

Uuid · uuid · required

revision

integer · min: 1 · required

status

string · enum · required

Enum values:

confirmed

cancelled

start_at

Instant · date-time · required

ISO 8601 instant with an offset.

end_at

Instant · date-time · required

ISO 8601 instant with an offset.

BookingResult

Booking · required

replayed

boolean

projection_state

ProjectionState · enum

Enum values:

pending

projected

failed

conflict

CreateBookingRequest

start_at

Instant · date-time · required

ISO 8601 instant with an offset.

end_at

Instant · date-time · required

ISO 8601 instant with an offset.

MoveBookingRequest

booking_id

Uuid · uuid · required

expected_revision

integer · min: 1 · required

The booking's current revision; a stale one is 409 stale_revision.

start_at

Instant · date-time · required

ISO 8601 instant with an offset.

end_at

Instant · date-time · required

ISO 8601 instant with an offset.

CreateEventRequest

summary

string · minLength: 1 · maxLength: 500 · required

start_at

Instant · date-time · required

ISO 8601 instant with an offset.

end_at

Instant · date-time · required

ISO 8601 instant with an offset.

description

string | null · maxLength: 8000

UpdateEventRequest

uid

string · minLength: 1 · maxLength: 200 · required

summary

string · minLength: 1 · maxLength: 500 · required

start_at

Instant · date-time · required

ISO 8601 instant with an offset.

end_at

Instant · date-time · required

ISO 8601 instant with an offset.

sequence

integer · min: 0 · required

RFC 5545 SEQUENCE; bump it on every change.

description

string | null · maxLength: 8000

EventWritten

uid

string · required

etag

string | null

StoredEvent

A managed calendar answers `ics`; a delegated Google calendar (#5340) answers `event`.

uid

string · required

ics

string

The VCALENDAR text the store holds (managed).

object

The Google event's fields (delegated_google).

etag

string | null

EventPage

object[] · required

next_cursor

string | null · required

GrantRequest

user_id

Uuid · uuid · required

can_create

boolean · required

can_move

boolean · required

can_cancel

boolean · required

Grant

userId

Uuid · uuid

canCreate

boolean

canMove

boolean

canCancel

boolean

BookingWebhookEvent

Sent to an external-agent owner's `webhook_url`, signed with its webhook secret (Standard Webhooks: `webhook-id` = `id`, `webhook-timestamp`, `webhook-signature: v1,<base64 HMAC-SHA256>`).

id

Uuid · uuid · required

type

string · enum · required

Enum values:

booking.created

booking.moved

booking.cancelled

booking.conflict

created_at

Instant · date-time · required

ISO 8601 instant with an offset.

object · required

CreateShareRequest

email

string · email · maxLength: 320 · required

caldav_account

string | null · email · maxLength: 320

The recipient's own login on the calendar store (local@domain), granted CalDAV read.

CalendarShare

id

Uuid · uuid

recipient_email

string

email_status

string · enum

Enum values:

pending

sent

failed

caldav

boolean

created_at

Instant · date-time

ISO 8601 instant with an offset.

revoked

boolean

CreatedShare

CalendarShare

object

rotated

integer · min: 0

How many earlier shares to this email were revoked.

MeshAvatarType

string · pattern: ^[a-z][a-z0-9_]{1,63…

An avatar type from the persona registry, e.g. language_tutor.

MeshOrganizationRef

string · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

MeshQuoteRequest

avatar_type

MeshAvatarType · pattern: ^[a-z][a-z0-9_]{1,63… · required

An avatar type from the persona registry, e.g. language_tutor.

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

MeshStatusRequest

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

MeshApproveRequest

requestId

Uuid · uuid · required

action

string · enum · required

Enum values:

approve

cancel

MeshPrincipal

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · kind="avatar" · requires: avatar_type
	type = object · kind="external_agent" · requires: external_agent_id

Properties for Variant 1:

kind

string · const · required

Const value: avatar

avatar_type

MeshAvatarType · pattern: ^[a-z][a-z0-9_]{1,63… · required

An avatar type from the persona registry, e.g. language_tutor.

MeshInviteRequest

MeshPrincipal · required

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

display_name

string · minLength: 1 · maxLength: 80

labels

string[] · maxItems: 16

MeshMemberRef

An existing member of the organization's mesh (re-mint its token, or confirm its node joined).

mesh_id

Uuid · uuid · required

member_id

Uuid · uuid · required

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

MeshRevokeRequest

member_id

Uuid · uuid · required

organization_id

MeshOrganizationRef · uuid

Required of service-role and signed-in callers. Ignored for a developer key: the key's own organization is always the one acted on.

reason

string · maxLength: 200

MeshMember

id

Uuid · uuid

principal_kind

string · enum

Enum values:

avatar

external_agent

avatar_type

string | null

external_agent_id

string | null · uuid

display_name

string | null

service

string

The name the member publishes, e.g. a2a://language_tutor.

state

string · enum

Enum values:

invited

enrolled

revoked

peer_id

string | null

The member node's libp2p peer id once it has joined.

MeshStatus

Where the organization's mesh stands. Never a credential.

mesh_id

Uuid · uuid · required

state

string · enum · required

Enum values:

reserved

provisioning

active

releasing

released

failed

slug

string · required

The mesh's public name, <org-slug>-<4 hex>.

host

string · enum · required

Enum values:

fly

local

control_plane_url

string | null · uri · required

ready

boolean · required

last_error

string | null · required

MeshMember[] · required

MeshQuote

slug

string · required

host

string · enum · required

Enum values:

fly

local

available

boolean · required

object · required

reason

string · enum

Enum values:

unknown_avatar

payment_not_confirmed

mesh_being_released

host_unconfigured

MeshStatus

Where the organization's mesh stands. Never a credential.

MeshEnrollment

Shown once (`Cache-Control: no-store`). The bootstrap token is one-use and valid 24 h.

member_id

Uuid · uuid · required

service_name

string · required

control_plane_url

string · uri · required

bootstrap_token

string · required

expires_at

string | null · date-time · required

MeshJoined

member_id

Uuid · uuid · required

state

string · const · required

Const value: enrolled

peer_id

string · required

service

string · required

MeshRevoked

member_id

Uuid · uuid · required

state

string · const · required

Const value: revoked

method

string · enum · required

Enum values:

ban

token_revoke

none

AppointmentCalendarRequest

action

string · enum · required

Enum values:

list_calendars

select_calendar

sync

staff_queue

link_contact

dismiss

communication_reconcile

communication_status

organizationId

Uuid · uuid · required

receptionistId

Uuid · uuid · required

actorUserId

Uuid · uuid

Service lane only; the staff member acted for.

calendarId

string · maxLength: 512

select_calendar.

eventId

Uuid · uuid

link_contact, dismiss.

contactId

string · pattern: ^people/[A-Za-z0-9_-…

link_contact.

AppointmentActionRequest

proof

string · minLength: 1 · maxLength: 4096 · required

DelegatedSetupRequest

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · operation="status" · requires: organizationId, employeeId
	type = object · operation="list_connections" · requires: organizationId, employeeId
	type = object · operation="list_calendars" · requires: organizationId, employeeId, connectionId
	type = object · operation="select_calendar" · requires: organizationId, employeeId, connectionId +1 more
	type = object · operation="replace_calendar" · requires: organizationId, employeeId, previousIdentityId +2 more
	type = object · operation="agent_calendar_connections" · requires: organizationId, requestId
	type = object · operation="agent_calendar_calendars" · requires: organizationId, requestId, connectionId
	type = object · operation="agent_calendar_bind" · requires: organizationId, requestId, connectionId +1 more

Properties for Variant 1:

DelegatedStatus

operation

const · required

Const value: status

organizationId

Uuid · uuid · required

employeeId

Uuid · uuid · required

DelegatedStatus

operation

const · required

Const value: status

organizationId

Uuid · uuid · required

employeeId

Uuid · uuid · required

DelegatedListConnections

operation

const · required

Const value: list_connections

organizationId

Uuid · uuid · required

employeeId

Uuid · uuid · required

DelegatedListCalendars

operation

const · required

Const value: list_calendars

organizationId

Uuid · uuid · required

employeeId

Uuid · uuid · required

connectionId

Uuid · uuid · required

DelegatedSelectCalendar

operation

const · required

Const value: select_calendar

organizationId

Uuid · uuid · required

employeeId

Uuid · uuid · required

connectionId

Uuid · uuid · required

calendarId

string · minLength: 1 · maxLength: 512 · required

DelegatedReplaceCalendar

operation

const · required

Const value: replace_calendar

organizationId

Uuid · uuid · required

employeeId

Uuid · uuid · required

previousIdentityId

Uuid · uuid · required

connectionId

Uuid · uuid · required

calendarId

string · minLength: 1 · maxLength: 512 · required

AgentCalendarConnections

#5340: the approving admin's live Google Calendar connections, for an agent calendar request waiting for Google consent.

operation

const · required

Const value: agent_calendar_connections

organizationId

Uuid · uuid · required

requestId

Uuid · uuid · required

AgentCalendarCalendars

#5340: the writable calendars of one of the approving admin's Google connections.

operation

const · required

Const value: agent_calendar_calendars

organizationId

Uuid · uuid · required

requestId

Uuid · uuid · required

connectionId

Uuid · uuid · required

AgentCalendarBind

#5340: bind the chosen Google calendar to the agent calendar and make it active. Refusals carry their own code: `google_reconnect_required` (revoked or expired consent), `google_scope_missing`, `google_calendar_not_writable`, `not_the_approver`, `request_not_awaiting_consent`, `calendar_bound_elsewhere`, `order_in_progress`.

operation

const · required

Const value: agent_calendar_bind

organizationId

Uuid · uuid · required

requestId

Uuid · uuid · required

connectionId

Uuid · uuid · required

calendarId

string · minLength: 1 · maxLength: 512 · required

NoSendResult

An action result. Calendar actions never send a message, so they echo `noSend`.

noSend

boolean · const

Const value:

ClaimRequest

An agent's claim on a .one resource (#5342). `product` picks the adapter; the rest are its options.

product

string · enum · required

Enum values:

calendar

agent_name

string · minLength: 1 · maxLength: 120 · required

Who is asking, as the approve page shows it (e.g. "Claude").

display_name

string · maxLength: 120

The calendar's name; the agent name when absent.

time_zone

string · maxLength: 64

An IANA zone; UTC when absent.

ClaimStarted

The RFC 8628 device authorization response in plain words.

claim_id

Uuid · uuid · required

product

string · required

status

string · enum · required

Enum values:

authorization_pending

approve_url

string · uri · required

For the human: https://<site>/approve/<token> (dev: dev.helpfulai.app).

poll_url

string · uri · required

poll_token

string · required

The agent's secret (acpp_…); shown once.

expires_at

string · date-time · required

expires_in

integer · required

Seconds the human has to approve (1800).

interval

integer · required

Seconds between polls (5).

next_step

string

ClaimPoll

claim_id

Uuid · uuid · required

product

string · required

status

string · enum · required

Enum values:

authorization_pending

approving

ready

access_denied

expired_token

failed

interval

integer

expires_at

string · date-time

code

string

failed: the order's refusal code.

resource

object

ready: what was ordered (calendar: calendar_id, calendar_href, external_agent_id, state).

object

ready: api_key (an hpx_ key, scope acp) on the FIRST ready poll only; null afterwards.

usage

object

ready: the endpoints and the owner parameter to send with the key.

message

string

ClaimApproveRequest

approve_token

string · minLength: 1 · maxLength: 200 · required

The token in the approve URL (acpa_…).

action

string · enum · required

Enum values:

view

approve

deny

organization_id

Uuid · uuid

view (for the quote) and approve: the organization the resource is for; the caller must be its company admin.

ClaimDecision

object · required

can_approve

boolean

reason

string

message

string

object

McpMessage

One JSON-RPC 2.0 message of the Model Context Protocol (or an array of them): initialize, ping, tools/list, tools/call, notifications/*.

jsonrpc

string · enum · required

Enum values:

2.0

method

string · required

id

string | integer | null

params

object

Error

error

string · required

code

string

details

object

Uuid

string · uuid

AssistantEmailDispatch

userAgentId

string · minLength: 1 · required

userId

string · minLength: 1 · required

messageId

string · minLength: 1 · required

assistantId

string | null

Null for personal or draft mode.

threadId

string | null

fromEmail

string | null

subject

string | null

body

string | null

replyStyle

string | null

draftMode

boolean | null

Create a Gmail draft instead of sending.

TelnyxMessagingEvent

A Telnyx messaging webhook. Only `message.received` is ingested.

object · required

InboundRedriveRequest

The reaper's redrive of a stalled claim (`x-worker-secret` lane).

claim_id

string · required

InboundReceipt

received

boolean

claim_id

string

duplicate

boolean

status

string

skipped

string

error

string · enum

Enum values:

claim_failed

fetch_failed

recovered

boolean

Redrive lane only.

terminal

boolean

Redrive lane only.

reason

string

Redrive lane only.

LivekitWebhookEvent

A LiveKit webhook event; SIP participant joins and leaves are metered.

event

string · required

createdAt

integer

object

ResendWebhookEvent

A Resend webhook. Only `email.received` is claimed.

type

string · required

data

object · required

InstanceQuoteRequest

customer_assistant_id

Uuid · uuid · required

area_code

string | null · pattern: ^[2-9][0-9]{2}$

phone_number

string | null · pattern: ^\+1[2-9][0-9]{9}$

An exact number to re-check instead of searching.

PersonaQuoteRequest

request_id

Uuid · uuid · required

InstanceQuote

quote_id

Uuid · uuid

customer_assistant_id

Uuid · uuid

organization_id

Uuid · uuid

phone_number

string

preferred_area_code_matched

boolean

requested_area_code

string | null

expires_at

string · date-time

area_code_unavailable

boolean

availability_message

string

object

requires_exact_number_approval

boolean · const

Const value:

PersonaQuote

request_id

Uuid · uuid

area_code

string | null

reserved

boolean

True when an unfinished order already holds this number.

quote

object | null

InstancePhoneApproveRequest

quote_id

Uuid · uuid · required

approved_phone_number

string · pattern: ^\+[1-9][0-9]{7,14}$ · required

InstancePhoneApproval

approved

boolean · const

Const value:

quote_id

Uuid · uuid

customer_assistant_id

Uuid · uuid

organization_id

Uuid · uuid

phone_number

string

state

string

activation_queued

boolean

order_placed

boolean

PhoneApproveRequest

requestId

Uuid · uuid · required

action

string · enum · required

Enum values:

approve

cancel

returnPath

string · maxLength: 256

avatarName

string · minLength: 1 · maxLength: 60

ActivateRequest

customer_assistant_id

Uuid · uuid · required

quote_id

Uuid · uuid · required

Activation

rent_paid

boolean · required

state

string · required

order_placed

boolean · required

phone_number

string | null

ProvisionRequest

customer_assistant_id

Uuid · uuid · required

Provisioning

phone_number

string | null

state

string

order_placed

boolean

voice_connection_ready

boolean

voice_route_ready

boolean

sms_profile_ready

boolean

sms_compliance_ready

boolean

sms_route_ready

boolean

active

boolean

CancelRequest

customer_assistant_id

Uuid · uuid · required

Cancellation

cancelled

boolean · const

Const value:

routing_stopped

boolean · const

Const value:

registered_calls_ended

boolean

registered_calls_pending

integer

rent_reconciliation

string · enum

Enum values:

none

portout

cancelled_uncharged

refunded

pending

phone_number

string | null

port_out_deadline

string | null · date-time

release_after

string | null · date-time