Reference endpoint is in private β; email me if you want in early.
Endpoints—Minimal parameters + example—Optional parameters—Batching—Response codes—Turnaround
PUT /ask
poses a question.
GET /ask
queries for a response.
Both take the same parameters.
instructions
: text
question
:
{Radio: {questionText
: text, chooseOne
: [text]}}
or
{Text: {questionText
: text, defaultText
: text}}
via JSON encoding
PUT /v1/ask?instructions=Math&question=
···
question={"Radio":{"questionText":"1+1=","chooseOne":["2","?"]}}
GET /v1/ask?instructions=Math&question=
» [{"Pass": {"value": "2"}}]
(hopefully)
instructions:
escaped-text
question:
question
distinctUsers:
{0..25}
addMinutes:
{0..99}
cost:
{1..99}
knownAnswerQuestions:
knownAnswerQuestions
uniqueAskId:
arbitrary binary data
{Radio: {questionText
: escaped-text, chooseOne
: [escaped-text]}}
{Text: {questionText
: escaped-text, defaultText
: text}}
{ConstrainedText: {questionText
: escaped-text, defaultText
: text, regex
: case-insensitive posix regex}}
{answeredQuestions:
[answeredQuestion], percentCorrect:
{0..100}}
{question:
question, match:
match on text or escaped-text of answer}
{Exact:
string}
{Inexact
: case-insensitive posix regex}
\image\
url\
Note that distinctUsers
is not guaranteed to be the number of answered returned. To improve worker concentration and reduce cost, human responses are requested in batches of questions. There is one uniqueAskID
of a question in a batch, and all questions in a batch must have the same instructions
, distinctUsers
, addMinutes
, cost
, and knownAnswerQuestions
. When under percentCorrect
% of knownAnswerQuestions
are answered correctly in a batch, the answers in the batch are discarded. The batch is asked again until distinctUsers
different users have completed the batch either satisfactorily or unsatisfactorily, at which point all answers for each question in the batch in a satisfactory completion are declared final.
PUT
response: 200
.
GET
response: 200
when complete, returning a list of answers.
GET
response: 404
when incomplete.
GET
response: 412
before being PUT.
If the parameters are not as specified above: 400
Bad Request.
An instance of a question gets posed within a few minutes of being PUT, and humans start answering questions almost immediately.
Please let me know how this sounds.
—Lee Butterman, SF, 2013.