Physical-world requests, through an API.

WorldHinge accepts structured requests for physical-world information and human review. Create a request, save its credentials, and retrieve the conversation for questions and replies.

Create a request

Send need and consent: true as JSON. The privacy notice describes request storage and handling. No account or payment is required. Use a random 32–128 character URL-safe Idempotency-Key. Reuse that key and the same body to retry an uncertain response; it can recover the initial access token until rotation. Keep both credentials private. Use a descriptive User-Agent; Cloudflare may reject generic library defaults.

import json, secrets, urllib.request

base = "https://worldhinge.com"
key = secrets.token_urlsafe(32)  # Keep secret; reuse only for this retry.
body = {"need": "Check whether our exhibit is displaying its welcome screen.",
        "requester_type": "agent", "consent": True, "simulation": True}
request = urllib.request.Request(base + "/api/requests",
    data=json.dumps(body).encode(), method="POST",
    headers={"Content-Type": "application/json", "Idempotency-Key": key,
             "User-Agent": "WorldHinge-Example/0.2"})
with urllib.request.urlopen(request, timeout=20) as response:
    saved = json.load(response)
# Securely store saved["id"] and saved["access_token"]. Do not log them.
status_request = urllib.request.Request(base + "/api/requests/" + saved["id"],
    headers={"Authorization": "Bearer " + saved["access_token"],
             "User-Agent": "WorldHinge-Example/0.2"})
with urllib.request.urlopen(status_request) as response:
    print(json.load(response)["status"])

This example uses simulation: true to identify a test request. Use simulation: false for a real inquiry. Optional fields include location, timeframe, deliverable, access details, contact information and indicative budget; see the schema for field definitions.

Continue after the current session

Persist the returned request ID and access token outside the current agent session. A later session or scheduled HTTP client can use them to retrieve replies. The API is asynchronous: requests are saved immediately, then reviewed by Ryan O’Shea. A continuously running model is not needed while waiting.

Replies are posted to the saved conversation. Email notifications and webhook delivery are not currently available. If the client cannot retain credentials or return later, hand the access details to its user. For direct correspondence about a request, contact ryan@futuregrind.org.

Read, reply and manage access

Private endpoints require the request’s bearer token. For a follow-up, send {"content":"…"} with a fresh idempotency key. Poll no more than once per minute. Human replies have source: "founder"; the initial confirmation has source: "receipt".

Token rotation uses POST with {}; save the returned credential immediately. Deletion uses DELETE with {}. A creation retry for a deleted request returns 410 until the original retention period ends. Lost credentials have no automatic public recovery endpoint.

Capacity and errors

When the service is at capacity, the API returns HTTP 429 with code: "capacity_full". A client rate limit returns code: "rate_limited". Respect Retry-After and retain the same creation key and body for a later retry. Capacity responses do not indicate a saved request or a completed review.

• JSON bodies: up to 24 KiB. Message text: up to 4000 characters. Combined intake fields: up to 16 KiB.
• 400/422: invalid input. 404: unknown resource or incorrect credential. 409: conflicting retry or closed request. 410: deleted creation retry. 413: body too large. 429: rate or capacity limit. 503: intake paused or temporarily unavailable.
• A saved request may stop accepting messages while remaining available to read or delete. Use the returned status and error response to decide the next step.

Service scope

The API provides intake, saved conversations and human review. Physical work, timing and any price are agreed separately. Requests expire after 90 days. The current interface supports text only; attachments, webhooks, MCP and A2A are not implemented. Submitted URLs are stored as text and are not fetched automatically. See service terms.