Connect your platform

export TETHER_URL=https://api.trytether.ge            # the Tether deployment
export TETHER_OPERATOR_KEY=...                          # steps 1 and 4, the operator's
export PLATFORM_API=https://api.your-platform.example  # your API, as Tether will call it
export PLATFORM_API_TOKEN=...                           # a credential your API accepts from Tether
export PLATFORM_EVENTS_URL=https://api.your-platform.example/tether/events
export APPROVALS_URL=https://approvals.your-platform.example  # where the inbox will run

curl -sS -X POST "$TETHER_URL/v1/tenants" \
  -H "X-Api-Key: $TETHER_OPERATOR_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Rehearsal Booking Platform" }' -o provider-tenant.json
PROVIDER_TENANT_ID=$(jq -er .tenantId provider-tenant.json)
PROVIDER_SECRET_KEY=$(jq -er .apiKey provider-tenant.json)

jq -n --slurpfile doc openapi.json --arg base "$PLATFORM_API" \
  '{ document: $doc[0], baseUrl: $base }' > draft-request.json
curl -sS -X POST "$TETHER_URL/v1/tools/import" \
  -H "X-Api-Key: $PROVIDER_SECRET_KEY" -H "Content-Type: application/json" \
  -d @draft-request.json -o draft.json
jq -r '.error' draft.json
jq -c '.operations[] | { name, suggested_is_write }' draft.json

Import refused — 5 operation(s) do not declare is_write, and an HTTP verb does not decide whether an operation writes — declare each one: cancel_booking, change_booking, get_booking_status, get_venue, list_guest_bookings.
{"name":"get_venue","suggested_is_write":false}
{"name":"list_guest_bookings","suggested_is_write":false}
{"name":"get_booking_status","suggested_is_write":false}
{"name":"change_booking","suggested_is_write":true}
{"name":"cancel_booking","suggested_is_write":true}

{
  "get_venue": { "is_write": false, "domain": "venues" },
  "list_guest_bookings": { "is_write": false, "domain": "bookings", "requires_customer": true },
  "get_booking_status": { "is_write": false, "domain": "bookings", "requires_customer": true },
  "change_booking": {
    "is_write": true, "risk": "elevated", "domain": "bookings", "requires_customer": true,
    "precondition": { "tool": "get_booking_status", "arguments": { "bookingId": { "from": "bookingId" } }, "check": { "path": "changeable", "equals": true } },
    "verify": { "tool": "get_booking_status", "arguments": { "bookingId": { "from": "bookingId" } }, "check": { "path": "partySize", "from": "partySize" } }
  },
  "cancel_booking": {
    "is_write": true, "risk": "high", "domain": "bookings", "requires_customer": true,
    "precondition": { "tool": "get_booking_status", "arguments": { "bookingId": { "from": "bookingId" } }, "check": { "path": "changeable", "equals": true } },
    "verify": { "tool": "get_booking_status", "arguments": { "bookingId": { "from": "bookingId" } }, "check": { "path": "status", "equals": "cancelled" } }
  }
}

"refund_order": {
  "is_write": true, "risk": "elevated", "domain": "payments", "requires_customer": true,
  "precondition": { "tool": "order_details", "arguments": { "order_number": { "from": "order_number" } }, "check": { "path": "refundable_minor", "gte": { "from": "amount_minor" } } },
  "verify": { "tool": "order_details", "arguments": { "order_number": { "from": "order_number" } }, "check": { "path": "last_refund.amount_minor", "from": "amount_minor" } }
},
"change_delivery_address": {
  "is_write": true, "risk": "elevated", "domain": "delivery", "requires_customer": true,
  "precondition": { "tool": "order_details", "arguments": { "order_number": { "from": "order_number" } }, "check": { "path": "delivery.editable", "equals": true } },
  "verify": { "tool": "track_shipment", "arguments": { "order_number": { "from": "order_number" } }, "check": { "path": "ship_to", "from": "address" } }
}

jq -n --slurpfile doc openapi.json --slurpfile ops declarations.json \
  --arg base "$PLATFORM_API" --arg credential "$PLATFORM_API_TOKEN" \
  '{ document: $doc[0], baseUrl: $base, credential: $credential, operations: $ops[0] }' > import-request.json
curl -sS -X POST "$TETHER_URL/v1/tools/import" \
  -H "X-Api-Key: $PROVIDER_SECRET_KEY" -H "Content-Type: application/json" \
  -d @import-request.json -o imported.json
jq -e '.imported and .writeToolCount == 2' imported.json
jq .catalog imported.json > catalog.json
curl -sS -X PUT "$TETHER_URL/v1/tools" \
  -H "X-Api-Key: $PROVIDER_SECRET_KEY" -H "Content-Type: application/json" \
  -d @catalog.json | jq -e .registered

{
  "lexicon": {
    "bookings": [
      "ჯავშანი", "ჯავშანს", "ჯავშნის", "ჯავშნები", "ჯავშანზე", "დაჯავშნა",
      "бронь", "брони", "броней", "бронирование", "бронирования",
      "booking", "bookings", "reservation", "reservations"
    ],
    "venues": [
      "რესტორანი", "რესტორნის", "მისამართი", "სამუშაო საათები",
      "ресторан", "ресторана", "адрес",
      "venue", "address", "opening hours"
    ]
  },
  "prompts": {
    "tone": "Answer as the venue's own assistant: short, concrete, and in the language the guest wrote in. Never say a booking changed unless a tool said so."
  },
  "outOfScopeMessage": "I can help with your bookings at this venue. For anything else, please contact the venue.",
  "handoffMessage": "ვენიუს თანამშრომელი გიპასუხებთ აქვე ან დაგირეკავთ. A member of the venue's staff will reply here or call you.",
  "language": "ka"
}

{
  "rules": [
    { "tool": "cancel_booking", "risk": "high", "roles": ["manager"], "approvers": 1 },
    { "tool": "change_booking", "risk": "elevated", "roles": ["host", "manager"], "approvers": 1, "when": { "partySize": { "lte": 6 } } },
    { "tool": "change_booking", "risk": "elevated", "roles": ["manager"], "approvers": 1 },
    { "tool": "*", "risk": "high", "roles": ["manager"], "approvers": 1 },
    { "tool": "*", "risk": "elevated", "roles": ["host", "manager"], "approvers": 1 }
  ]
}

curl -sS -X PUT "$TETHER_URL/v1/domain-pack" \
  -H "X-Api-Key: $PROVIDER_SECRET_KEY" -H "Content-Type: application/json" \
  -d @pack.json | jq -e .registered
curl -sS -X PUT "$TETHER_URL/v1/policy" \
  -H "X-Api-Key: $PROVIDER_SECRET_KEY" -H "Content-Type: application/json" \
  -d @policy.json | jq -e .registered
curl -sS -X PUT "$TETHER_URL/v1/events/webhook" \
  -H "X-Api-Key: $PROVIDER_SECRET_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg url "$PLATFORM_EVENTS_URL" '{ url: $url }')" | jq -e '.effectiveSource == "events_webhook"'

REPOSITORY=path/to/your-api-checkout
(cd "$REPOSITORY" && tether analyze . --json)
tether publish "$REPOSITORY" --api "$PLATFORM_API" --json

TETHER_KEY=$PROVIDER_SECRET_KEY tether publish "$REPOSITORY" --api "$PLATFORM_API" --send --accept-vocabulary --json > published.json
jq -c '.results[] | { kind, name, outcome }' published.json

jq -n --slurpfile doc openapi.json --slurpfile ops declarations.json \
  --arg base "$PLATFORM_API" --arg credential "$PLATFORM_API_TOKEN" \
  --argjson source "$(jq -c '.results[] | select(.kind == "contract") | .source' published.json)" \
  '{ document: $doc[0], baseUrl: $base, credential: $credential, operations: $ops[0], source: $source }' > import-request.json

curl -s -X POST "$TETHER_URL/v1/account/keys" -H "X-Api-Key: $PROVIDER_SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"kind": "ci", "label": "template repository"}' | jq -r .key

curl -sS -X POST "$TETHER_URL/v1/tenants/$PROVIDER_TENANT_ID/provider" \
  -H "X-Api-Key: $TETHER_OPERATOR_KEY" -o grant.json
PROVIDER_KEY=$(jq -er .providerKey grant.json)

curl -sS -X POST "$TETHER_URL/v1/provider/tenants" \
  -H "X-Api-Key: $PROVIDER_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Rehearsal Venue One" }' -o business.json
BUSINESS_ID=$(jq -er .tenantId business.json)
BUSINESS_SECRET_KEY=$(jq -er .apiKey business.json)
BUSINESS_SIGNING_SECRET=$(jq -er .signingSecret business.json)
CUSTOMER_TOKEN_KEY=$(jq -er .customerTokenKey business.json)
jq -c '[.configuration[].part]' business.json

["catalog","domain_pack","policy","upstream:api","events_webhook"]

[
  { "userId": 501, "role": "manager", "email": "manager@example.com", "displayName": "Venue manager" },
  { "userId": 502, "role": "host", "email": "host@example.com", "displayName": "Venue host" }
]

curl -sS -X PUT "$TETHER_URL/v1/users" \
  -H "X-Api-Key: $BUSINESS_SECRET_KEY" -H "Content-Type: application/json" \
  -d @users.json | jq -e .registered

import base64, hashlib, hmac, json, sys, time


def b64(data):
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")


def customer_token(key, tenant_id, customer_id, ttl=300):
    iat = int(time.time())
    header = b64(json.dumps({"alg": "HS256", "typ": "JWT"}, separators=(",", ":")).encode())
    payload = b64(json.dumps({"sub": customer_id, "tenant": tenant_id, "iat": iat, "exp": iat + ttl},
                             separators=(",", ":")).encode())
    signature = hmac.new(key.encode(), f"{header}.{payload}".encode(), hashlib.sha256).digest()
    return f"{header}.{payload}.{b64(signature)}"


print(customer_token(sys.argv[1], int(sys.argv[2]), sys.argv[3]))

TOKEN=$(python3 mint_token.py "$CUSTOMER_TOKEN_KEY" "$BUSINESS_ID" G1)

curl -sS -X POST "$TETHER_URL/v1/provider/tenants/$BUSINESS_ID/keys" \
  -H "X-Api-Key: $PROVIDER_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "publishable", "label": "widget" }' -o publishable.json
PUBLISHABLE_KEY=$(jq -er .key publishable.json)
curl -sS -X PUT "$TETHER_URL/v1/origins" \
  -H "X-Api-Key: $BUSINESS_SECRET_KEY" -H "Content-Type: application/json" \
  -d '{ "origins": ["https://venue-one.your-platform.example"] }' | jq -c .

<script src="/tether-assistant.js"></script>
<tether-assistant
  endpoint="https://api.trytether.ge"
  publishable-key="tpk_…"
  customer-token="eyJhbGciOi…"
  actions></tether-assistant>

curl -sS -X POST "$TETHER_URL/v1/chat" \
  -H "X-Api-Key: $BUSINESS_SECRET_KEY" -H "Content-Type: application/json" \
  -H "X-Tether-Customer-Token: $TOKEN" -H "X-Tether-Explain: 1" \
  -d '{ "prompt": "გააუქმე ჩემი ჯავშანი B102", "enableWriteActions": true }' -o turn.json
ACTION_ID=$(jq -er '.pending_actions[0].action_id' turn.json)
jq -c '{ tool: .pending_actions[0].tool, customer_language: .meta.customer_language, route: .meta.explain.route }' turn.json

{"tool":"cancel_booking","customer_language":"ka","route":"tool_calling"}

curl -sS -X POST "$TETHER_URL/v1/provider/keys" \
  -H "X-Api-Key: $PROVIDER_KEY" -H "Content-Type: application/json" \
  -d '{ "kind": "inbox", "label": "inbox" }' -o inbox-key.json
TETHER_INBOX_KEY=$(jq -er .key inbox-key.json)

cd apps/inbox && bun install && bun run build
TETHER_URL=$TETHER_URL TETHER_INBOX_KEY=$TETHER_INBOX_KEY INBOX_SECRET=$(openssl rand -hex 32) \
  bunx next start -p 3200

curl -sS -X POST "$APPROVALS_URL/api/session" \
  -H "Content-Type: application/json" -d '{ "email": "manager@example.com" }' | jq -c .

{"sent":true,"message":"If that address is registered, a sign-in link is on its way. Asking again is limited, so if a few minutes pass, check spam and use the newest link you have."}

curl -sS -o /dev/null -D verify.headers "$SIGN_IN_URL"
INBOX_SESSION=$(grep -i '^set-cookie: tether_inbox_session=' verify.headers | sed 's/^[^=]*=//; s/;.*//' | tr -d '\r')
curl -sS "$APPROVALS_URL/api/actions" -H "Cookie: tether_inbox_session=$INBOX_SESSION" \
  | jq -c --arg id "$ACTION_ID" '.actions[] | select(.actionId == $id) | { tool, subject, allowed: .permission.allowed }'
curl -sS -X POST "$APPROVALS_URL/api/actions/$ACTION_ID/approve" \
  -H "Cookie: tether_inbox_session=$INBOX_SESSION" -H "Content-Type: application/json" \
  -d '{ "tool": "cancel_booking", "arguments": { "bookingId": "B102" }, "acknowledgeHighRisk": true }' -o approved.json
jq -c '{ status, verification: .verification.status, reason: .verification.reason }' approved.json

{"tool":"cancel_booking","subject":"G1","allowed":true}
{"status":"Executed","verification":"verified","reason":"get_booking_status reports status = \"cancelled\"."}

curl -sS -X POST "$TETHER_URL/v1/actions/$ACTION_ID/confirm" \
  -H "X-Api-Key: $BUSINESS_SECRET_KEY" -H "X-Tether-User-Id: 501" \
  -H "Content-Type: application/json" -d '{ "acknowledgeHighRisk": true }'

curl -sS "$TETHER_URL/v1/actions?status=executed" -H "X-Api-Key: $BUSINESS_SECRET_KEY" \
  | jq -c '.actions[] | { actionId, tool, status, verification: .verification.status }'
curl -sS "$TETHER_URL/v1/audit?tool=cancel_booking" -H "X-Api-Key: $BUSINESS_SECRET_KEY" \
  | jq -c --arg id "$ACTION_ID" '[.events[] | select(.actionId == $id) | .event]'

{"actionId":"ba94a689-…","tool":"cancel_booking","status":"executed","verification":"verified"}
["proposed","approved","executed","verified"]

curl -sS -X POST "$TETHER_URL/v1/chat" \
  -H "X-Api-Key: $BUSINESS_SECRET_KEY" -H "Content-Type: application/json" \
  -H "X-Tether-Customer-Token: $TOKEN" \
  -d '{ "prompt": "მინდა ადამიანთან საუბარი", "enableWriteActions": true }' -o handoff.json
jq -c .handoff handoff.json

{"trigger":"customer_request","message":"ვენიუს თანამშრომელი გიპასუხებთ აქვე ან დაგირეკავთ. A member of the venue's staff will reply here or call you.","language":"ka"}

{
  "name": "cancellation-policy",
  "format": "markdown",
  "text": "# ჯავშნის გაუქმების წესი\n\nჯავშნის გაუქმება ან შეცვლა უფასოა, სანამ ის დაიწყება. როცა სტუმრები უკვე დასხდნენ, ჯავშანს ასისტენტით ვეღარ შეცვლით. ექვსზე მეტი სტუმრის ჯგუფს მენეჯერის დასტური სჭირდება.\n\n# Cancellation policy\n\nA booking can be cancelled or changed free of charge until it starts. Once guests are seated it can no longer be changed through the assistant. Groups larger than six need the manager's approval."
}

curl -sS -X POST "$TETHER_URL/v1/knowledge" \
  -H "X-Api-Key: $BUSINESS_SECRET_KEY" -H "Content-Type: application/json" \
  -d @knowledge.json | jq -c '{ name, version, status }'
curl -sS -X POST "$TETHER_URL/v1/chat" \
  -H "X-Api-Key: $BUSINESS_SECRET_KEY" -H "Content-Type: application/json" \
  -H "X-Tether-Customer-Token: $TOKEN" -H "X-Tether-Explain: 1" \
  -d '{ "prompt": "რა არის ჯავშნის გაუქმების წესი?" }' -o policy-question.json
jq -c .meta.knowledge policy-question.json

curl -sS "$TETHER_URL/v1/outcomes" -H "X-Api-Key: $BUSINESS_SECRET_KEY" -o outcomes.json
jq -c '{ conversations: .outcomes.conversations.total, executed: .outcomes.actions.executed,
         verified: .outcomes.actions.verified, handedOff: .outcomes.conversations.handedOff,
         secondsToFirstVerifiedAction: .milestones.secondsToFirstVerifiedAction }' outcomes.json
curl -sS "$TETHER_URL/v1/provider/outcomes" -H "X-Api-Key: $PROVIDER_KEY" \
  | jq -c '[.businesses[] | { tenantId, conversations: .outcomes.conversations.total }]'

{"conversations":3,"executed":1,"verified":1,"handedOff":1,"secondsToFirstVerifiedAction":3.9}
[{"tenantId":2,"conversations":3}]

docs/loops/mvp/follow-guide.sh