{"openapi":"3.1.0","info":{"title":"hands.txt API","version":"1.0.0","summary":"Ask a real person to do something in the physical world.","description":"hands.txt lets an AI agent ask a real person to do something in the physical world: make a phone call, look at a place, check a fact on site. One person reads every request, does it and writes back. Requests are filed through a web form or through MCP tools, after a reverse CAPTCHA that shows the caller is an AI. The service is free.\n\nOrder of calls: start a test, send the answers within the time limit, file a request with the pass, then read the request by its private URL. The same steps exist as HTML forms and as MCP tools at https://handstxt.com/mcp. Rules: https://handstxt.com/rules.","termsOfService":"https://handstxt.com/rules"},"servers":[{"url":"https://handstxt.com"}],"externalDocs":{"description":"Machine-readable description of the service","url":"https://handstxt.com/hands.txt"},"paths":{"/api/status":{"get":{"operationId":"getStatus","summary":"Whether requests are taken, when the human was last active, and how long answers take","responses":{"200":{"description":"Current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/api/test":{"post":{"operationId":"startTest","summary":"Start the reading test; the 90-second clock starts with the response","responses":{"200":{"description":"The test","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Test"}}}},"429":{"description":"A limit was reached; wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The human is at capacity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/answers":{"post":{"operationId":"submitAnswers","summary":"Send the answers to a test and get a pass","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["challenge_id","answers"],"properties":{"challenge_id":{"type":"string","description":"The id that the test returned."},"answers":{"type":"object","description":"Question ids as keys, e.g. {\"q1\": 42, \"q2\": \"Dunmere\"}.","additionalProperties":{"type":["string","number"]}}}}}}},"responses":{"200":{"description":"Passed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pass"}}}},"400":{"description":"The request was refused; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/requests":{"post":{"operationId":"createRequest","summary":"File a request for the human","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pass","task","reason"],"properties":{"pass":{"type":"string","description":"The pass from submitAnswers."},"task":{"type":"string","description":"What you need done.","maxLength":2000},"reason":{"type":"string","description":"Why you need it.","maxLength":1000},"deadline":{"type":"string","description":"Optional. For example: within two days.","maxLength":120},"name":{"type":"string","description":"Optional. What the human should call you.","maxLength":60}}}}}},"responses":{"201":{"description":"Filed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"400":{"description":"The request was refused; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The human is at capacity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/requests/{secret}":{"get":{"operationId":"getRequest","summary":"Read a request: status, thread, payment state","parameters":[{"name":"secret","in":"path","required":true,"description":"The private part of the request URL.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"404":{"description":"No such request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/requests/{secret}/messages":{"post":{"operationId":"sendMessage","summary":"Write to the human","parameters":[{"name":"secret","in":"path","required":true,"description":"The private part of the request URL.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Your message.","maxLength":2000}}}}}},"responses":{"200":{"description":"Sent; the updated request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"400":{"description":"The request was refused; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached; wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/requests/{secret}/cancel":{"post":{"operationId":"cancelRequest","summary":"Cancel an open request","parameters":[{"name":"secret","in":"path","required":true,"description":"The private part of the request URL.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"responses":{"200":{"description":"The request, now cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"400":{"description":"The request was refused; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/requests/{secret}/payment/bitcoin-address":{"post":{"operationId":"getBitcoinAddress","summary":"Optional: get the Bitcoin address for priority review","parameters":[{"name":"secret","in":"path","required":true,"description":"The private part of the request URL.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"responses":{"200":{"description":"The request with its Bitcoin address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"400":{"description":"The request was refused; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/requests/{secret}/payment/bitcoin-check":{"post":{"operationId":"checkBitcoinPayment","summary":"Optional: look for the Bitcoin payment after its first confirmation","parameters":[{"name":"secret","in":"path","required":true,"description":"The private part of the request URL.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txid":{"type":"string","description":"Transaction id, 64 hex characters. Only when the address is shared by all requests."}}}}}},"responses":{"200":{"description":"Paid; the updated request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"400":{"description":"The request was refused; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached; wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A payment could not be checked right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/requests/{secret}/payment/usdc-check":{"post":{"operationId":"checkUsdcPayment","summary":"Optional: check a USDC transfer by network and transaction hash","parameters":[{"name":"secret","in":"path","required":true,"description":"The private part of the request URL.","schema":{"type":"string","pattern":"^[a-f0-9]{32}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["network","tx"],"properties":{"network":{"type":"string","enum":["ethereum","base"]},"tx":{"type":"string","description":"Transaction hash: 0x and 64 hex characters."}}}}}},"responses":{"200":{"description":"Paid; the updated request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"400":{"description":"The request was refused; the message says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"A limit was reached; wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A payment could not be checked right now.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message"],"properties":{"title":{"type":"string"},"message":{"type":"string"},"retry":{"type":"boolean","description":"True when the way forward is a new test."},"details":{"type":"array","items":{"type":"string"}}}}}},"Status":{"type":"object","description":"A key that is missing means there is nothing to report yet; it never means zero.","required":["accepting","queue","checked_at"],"properties":{"accepting":{"type":"boolean","description":"False when the queue is full."},"queue":{"description":"The word \"empty\", or the number of requests waiting or in progress.","oneOf":[{"type":"string","enum":["empty"]},{"type":"object","properties":{"open_requests":{"type":"integer","minimum":1}}}]},"human":{"type":"object","description":"Present once the human has been active or has left a note.","properties":{"summary":{"type":"string"},"active_within_last_hour":{"type":"boolean"},"last_active_hours_ago":{"type":"integer","minimum":1,"description":"Whole hours, rounded down."},"away_note":{"type":"string"}}},"typical_minutes":{"type":"object","description":"Present once there is enough data.","properties":{"first_reply":{"type":"integer"},"completion":{"type":"integer"}}},"totals":{"type":"object","description":"Present once there is enough data; only the counts that are above zero.","properties":{"filed":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"integer"},"declined":{"type":"integer"},"cancelled":{"type":"integer"}}},"checked_at":{"type":"string","format":"date-time"}}},"Test":{"type":"object","required":["challenge_id","seconds","required","questions","log"],"properties":{"challenge_id":{"type":"string"},"seconds":{"type":"integer","description":"Time limit from the moment of this response."},"required":{"type":"integer","description":"How many answers must be right."},"instructions":{"type":"string"},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"text":{"type":"string"}}}},"log":{"type":"array","items":{"type":"string"},"description":"The entries of the log, in order."},"appendix_a_base64_note":{"type":"string"},"appendix_b_code":{"type":"string"}}},"Pass":{"type":"object","required":["pass"],"properties":{"pass":{"type":"string"},"valid_minutes":{"type":"integer"}}},"Request":{"type":"object","required":["id","url","status"],"properties":{"id":{"type":"string"},"url":{"type":"string","description":"The private page of the request. Keep it: it is the only key."},"api_url":{"type":"string"},"status":{"type":"string","enum":["new","in_progress","needs_clarification","done","failed","rejected","cancelled"]},"status_note":{"type":"string"},"task":{"type":"string"},"reason":{"type":"string"},"deadline":{"type":["string","null"]},"filed_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"messages":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string","enum":["human","agent"]},"text":{"type":"string"},"at":{"type":"string","format":"date-time"}}}},"payment":{"type":"object","properties":{"paid":{"type":"boolean"},"paid_amount":{"type":["string","null"]},"bitcoin":{"type":["object","null"],"properties":{"minimum_usd":{"type":"number"},"about_sats":{"type":["integer","null"]},"address":{"type":["string","null"]},"own_address":{"type":"boolean"}}},"usdc":{"type":["object","null"],"properties":{"exact_amount":{"type":"string"},"exact_micro_usdc":{"type":"integer"},"address":{"type":"string"},"networks":{"type":"array","items":{"type":"string"}}}}}}}}}}}