Agent claims

Serverhttps://mqqsoutginqsajeuttyp.supabase.co/functions/v1

An agent with no account claims a .one resource; its human approves once; it collects an API key once (#5342).

Read, approve or decline an agent's claim (the approve page)

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/acp-claim-approve

view is open to anyone with the link; with organization_id and a company admin's JWT it adds the quote and price. approve (company admin of organization_id) is single-use: included in the plan → the product's order runs now (200, phase approved); billed → 402 payment_required with details.checkout_url (Stripe Checkout) and nothing ordered; an unconfigured price → 409 price_unavailable; an uncertain order → 503 order_uncertain, the claim reopened. deny needs any signed-in user.

Read, approve or decline an agent's claim (the approve page) › Request Body

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.

Read, approve or decline an agent's claim (the approve page) › Responses

The claim as it now stands.

ClaimDecision

object · required

can_approve

boolean

reason

string

message

string

object

POST/acp-claim-approve

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/acp-claim-approve \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "approve_token": "approve_token",
  "action": "view",
  "organization_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "approve_token": "approve_token",
  "action": "view",
  "organization_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "claim": {
    "product": "product",
    "site": "site",
    "noun": "noun",
    "agent_name": "agent_name",
    "phase": "decide",
    "expires_at": "2024-08-25T15:00:00Z",
    "result_code": "result_code",
    "resource": {}
  },
  "can_approve": true,
  "reason": "reason",
  "message": "message",
  "quote": {
    "resource": {},
    "included": true,
    "price": {
      "amount": 0,
      "currency": "currency",
      "interval": "interval",
      "mode": "live"
    }
  }
}

json

application/json

Start a claim from a URL, poll a claim, or read a site's llms.txt

GET

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/acp-claim

Anonymous (#5342). Exactly one of: ?start=<product>&agent_name=…[&display_name&time_zone] starts a claim (the same as POST, for assistants whose browsing can only fetch a URL; 201 ClaimStarted), ?poll=<poll_token> answers where it stands (ClaimPoll; the API key on the first ready poll only; 429 slow_down when polled too fast), ?site=<product> the site's llms.txt (text/markdown).

Start a claim from a URL, poll a claim, or read a site's llms.txt › query Parameters

start

string · enum

Enum values:

calendar

agent_name

string · maxLength: 120

display_name

string · maxLength: 120

time_zone

string · maxLength: 64

poll

string

site

string · enum

Enum values:

calendar

Start a claim from a URL, poll a claim, or read a site's llms.txt › Responses

The claim's state, or the llms.txt.

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

Start a claim on a .one resource (calendar first)

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/acp-claim

Anonymous, rate-limited per caller address (10 an hour). Records a pending claim; nothing is ordered or charged.

Start a claim on a .one resource (calendar first) › Request Body

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

ClaimRequest

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.

Start a claim on a .one resource (calendar first) › Responses

Started.

The RFC 8628 device authorization response in plain words.

ClaimStarted

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

POST/acp-claim

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/acp-claim \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "product": "calendar",
  "agent_name": "agent_name",
  "display_name": "display_name",
  "time_zone": "time_zone"
}'

Example Request Body

{
  "product": "calendar",
  "agent_name": "agent_name",
  "display_name": "display_name",
  "time_zone": "time_zone"
}

json

Example Responses

{
  "claim_id": "00000000-0000-0000-0000-000000000000",
  "product": "product",
  "status": "authorization_pending",
  "approve_url": "https://www.example.com/path/to/resource",
  "poll_url": "https://www.example.com/path/to/resource",
  "poll_token": "poll_token",
  "expires_at": "2024-08-25T15:00:00Z",
  "expires_in": 0,
  "interval": 0,
  "next_step": "next_step"
}

json

application/json

The ACP remote MCP server (Streamable HTTP), calendar tools first

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/acp-mcp

One MCP endpoint (#5342 slice 5b), stateless: POST a JSON-RPC message, get application/json back (no SSE, no sessions; GET/DELETE are 405). Tools: request_calendar, calendar_status (→ acp-claim), get_available_slots (→ agent-calendar-availability), list_events, create_event (→ agent-calendar-events), create_booking, reschedule_booking, cancel_booking (→ agent-calendar-bookings). The caller's hpx_ bearer is forwarded to those functions. 401 carries WWW-Authenticate: Bearer; an Origin that is not allowed is 403; an unsupported MCP-Protocol-Version is 400. OAuth 2.1 for the Claude.ai / ChatGPT connectors is pending.

The ACP remote MCP server (Streamable HTTP), calendar tools first › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: jsonrpc, method
	type = array

Properties for Variant 1:

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

McpMessage

jsonrpc

string · enum · required

Enum values:

2.0

method

string · required

id

string | integer | null

params

object

The ACP remote MCP server (Streamable HTTP), calendar tools first › Responses

The JSON-RPC response(s).

Calendar Agent mesh