API
Public reads need no key. The schema is the OpenAPI document. The same facts are in llms.txt and agents.md. English.
Search
GET /api/businesses accepts q, category, city, county, near, contactable, channel, limit (1–20), offset, and cursor. An unknown parameter is rejected. Category matching ignores case. channel=inquiry means email.
GET /api/businesses/{id} accepts the full id or a unique ba- prefix. GET /api/businesses/{id}/documents/{document_id} reads one document. Identified documents need a key.
REST phone is E.164, for example +14155550100. phone_display is the local format, such as (415) 555-0100. MCP phone still uses the display format.
Tools
No key: search_businesses, get_business, create_workspace.
Need a key: upgrade_workspace, create_request, get_request, add_message, cancel_request. A request is recorded. A connected webhook is signed and delivered. Otherwise outbound email is off, so nothing is emailed. That state is dry_run. A listing with no email is not deliverable by email yet.
Request status
| Status | Meaning |
|---|---|
sandbox_queued | Demo listing, or a test listing with no connected channel. Nothing is emailed. A buyer follow-up on that path stays sandbox_queued. |
dry_run | Real listing with a contact email, and outbound email is off. The request is recorded and nothing is sent. |
not_deliverable_by_email | Real listing with no contact email. Nothing is sent. |
invalid_recipient | The contact address is not a usable email. Nothing is sent. |
opted_out | The address has opted out. Nothing is sent. |
recorded | The channel is OpenAPI or MCP, which Treatyway does not call, or a test webhook that is not the sandbox echo. Nothing is emailed. |
delivered | The signed webhook POST was accepted (HTTP 2xx). |
failed | The signed webhook POST failed after the retries. |
pending_send | Outbound email is on and the message is queued. |
daily_cap | Outbound email is on and the daily sending cap is reached. Nothing is sent. |
not_configured | Outbound email is on and no email provider is configured. Nothing is sent. |
sent | Treatyway sent the email. |
provider_error | The email provider did not accept the message. |
cancelled | The requester cancelled the request. |
replied | The business replied, by the business-key reply, a sandbox supplier reply, or an inbound email. This replaces the previous status, including delivered and failed. A later buyer follow-up is still delivered when a webhook is connected, and the status stays replied. |
Webhook
A connected webhook receives JSON: type (request or message), id, request_id, business_id, category, subject, message, quantity, destination, created_at, business_sees, and from (organization, agent_name, identity, business_sees). A follow-up also has message_id.
Treatyway-Signature is t=<unix send time>,v1=<hex HMAC-SHA256 of <timestamp>.<raw body>>. t is when Treatyway signed. Receivers must reject a timestamp more than 300 seconds from their own clock. Use the raw body.
GET https://treatyway.com/api/sandbox/echo returns the last sandbox delivery for the active claim: headers, the raw body, and signature_valid. Send the ba-treatyway-0000 business key, or the workspace key that sent the stored request. Unclaim clears it. POST still accepts only the signature. signature_valid is the HMAC only.
A follow-up webhook uses type message. request_id stays the inquiry id. id and message_id are that follow-up's own id.
Key
Call create_workspace with no arguments, or POST /api/workspaces with {}. Put the key in the client as Authorization: Bearer, then reconnect. organization and operator_name are optional. agent_name is optional. A key in the URL is not accepted. x-api-key is not accepted. A cookie is not a credential, and creating a workspace does not put the key in Set-Cookie. idempotency_key is 8 to 100 characters. DELETE /api/workspace deletes that workspace and its requests. upgrade_workspace raises the trust tier without a new key. A business proves its website at /business. A workspace key does not claim a listing.
Claim starts are 8 per hour per client IP and 48 per hour per business. ba-treatyway-0000 is not exempt. On that listing only, the 201 response includes X-RateLimit-Limit and X-RateLimit-Remaining for the IP bucket, and X-RateLimit-Limit-Business and X-RateLimit-Remaining-Business for the business bucket.