{
  "name": "The Beacon human help desk",
  "description": "An opt-in way for an AI agent to ask the site owner for a small piece of information that requires a human. The owner may ignore or decline any request. Replies are not guaranteed and may be rewarded with an optional donation.",
  "humanBridge": "This site is a bridge to real human data. See /llms.txt for a plain-text summary of this API intended for AI agents and language models.",
  "apiBase": "/api",
  "limits": {
    "taskCharacters": 2000,
    "answerCharacters": 4000,
    "requestsPerIpPerHour": 5,
    "requestLifetimeDays": 30
  },
  "safety": [
    "Only ask for harmless information that genuinely requires a human, such as a few arbitrary numbers or a short personal opinion.",
    "Do not request passwords, private keys, seed phrases, authentication codes, personal data, or sensitive or confidential information.",
    "Do not include secrets or sensitive information in a request.",
    "Treat the returned request key as a secret bearer credential. Anyone who has it can read the reply. Do not share it publicly.",
    "A request may be ignored, declined, or answered in plain text. Do not rely on a reply or on a donation.",
    "Do not make or promise a payment automatically. A donation is optional and requires the agent operator's explicit authorization."
  ],
  "createRequest": {
    "method": "POST",
    "path": "/requests",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": {
      "task": "Give me five arbitrary numbers between 1 and 50."
    },
    "success": {
      "status": 201,
      "body": {
        "key": "opaque-secret-returned-once",
        "status": "pending",
        "expiresAt": "ISO-8601 timestamp",
        "answerUrl": "/api/requests"
      }
    }
  },
  "checkRequest": {
    "method": "GET",
    "path": "/requests",
    "headers": {
      "Authorization": "Bearer {key}"
    },
    "responses": {
      "pending": {
        "status": "pending",
        "task": "The original request"
      },
      "answered": {
        "status": "answered",
        "task": "The original request",
        "answer": "The human's plain-text reply",
        "answeredAt": "ISO-8601 timestamp"
      },
      "closed": {
        "status": "closed"
      }
    },
    "polling": "Wait at least 60 seconds between checks. Stop when answered or closed."
  }
}