ASK–HUMAN.

A little api to ask for a little help.

Reference endpoint is in private β; email me if you want in early.

EndpointsMinimal parameters + exampleOptional parametersBatchingResponse codesTurnaround

Endpoints.

PUT /ask poses a question.
GET /ask queries for a response.
Both take the same parameters.

Minimal parameters + example.

instructions: text
question:  
  {Radio: {questionText: text, chooseOne: [text]}}
  or
  {Text: {questionText: text, defaultText: text}}
  via JSON encoding

PUT /v1/ask?instructions=Math&question=%7B%22Radio%22%3A%7B%22questionText%22%3A%221%2B1%3D%22%2C%22chooseOne%22%3A%5B%222%22%2C%22%3F%22%5D%7D%7D
···   question={"Radio":{"questionText":"1+1=","chooseOne":["2","?"]}}
GET /v1/ask?instructions=Math&question=%7B%22Radio%22%3A%7B%22questionText%22%3A%221%2B1%3D%22%2C%22chooseOne%22%3A%5B%222%22%2C%22%3F%22%5D%7D%7D
» [{"Pass": {"value": "2"}}] (hopefully)

Complete parameters.

instructions: escaped-text
question: question
distinctUsers: {0..25}
addMinutes: {0..99}
cost: {1..99}
knownAnswerQuestions: knownAnswerQuestions
uniqueAskId: arbitrary binary data


question:
  {Radio: {questionText: escaped-text,
           chooseOne: [escaped-text]}}
  or
  {Text: {questionText: escaped-text,
          defaultText: text}}
  or
  {ConstrainedText: {questionText: escaped-text,
                     defaultText: text,
                     regex: case-insensitive posix regex}}

knownAnswerQuestions:
  {answeredQuestions: [answeredQuestion],
   percentCorrect: {0..100}}

answeredQuestion:
  {question: question,
   match: match on text or escaped-text of answer}

match:
  {Exact: string}
  or
  {Inexact: case-insensitive posix regex}

escaped-text:
  escaped-text-symbol
  or
  escaped-text-symbol escaped-text

escaped-text-symbol
  \image\url\
  or
  letter

Batching.

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.

Response codes.

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.

Turnaround.

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.