API Documentation

You can currently use 3 endpoints for different actions:

To create a new job, POST a JSON file to the following endpoint:

https://duke.pollstr.io/uploadAPI/

The following is the JSON schema for this file:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://duke.pollstr.io/uploadAPI",
  "title": "Job upload",
  "description": "This JSON file is used to create new jobs in pollstr.io.",
  "type": "object",
  "properties": {
    "config": {
      "description": "Configuration parameters of the job to be created",
      "type": "object",
      "properties": {
        "user": {
          "description": "Username for pollstr.io",
          "type": "string"
        },
        "password": {
          "description": "Password for your pollstr.io account",
          "type": "string"
        },
        "job_name": {
          "description": "Name for the job you are creating",
          "type": "string",
          "maxLength": 40
        },
        "language": {
          "description": "The language used in your text. We currently accept 6 languages.",
          "type": "string",
          "enum": ["english", "spanish", "italian", "german", "french", "portuguese"]
        },
        "no_times_to_verify": {
          "description": "The number of times human classifiers will classify each line of text. The higher the number, the greater the accuracy and the cost. It can be 1, 3 or 5 times.",
          "type": "number",
          "enum": [1,3,5]
        },
        "tags": {
          "description": "These are the tags to be applied to your text.",
          "type": "array",
          "maxItems": 10,
          "items": {
            "type": "object",
            "properties":{
              "tag_name": {
                "description": "This is the name of the tag to be applied to your text. It should be short but descriptive. For example: Positive",
                "type": "string",
                "maxLength": 20
              },
              "tag_desc": {
                "description": "This is the description of the tag that will be shown to human classifiers once they start working on your job. This can be longer than the tag name. Example: Comments that show appreciation or good standing with the company",
                "type": "string",
                "maxLength": 100
              }
            },
            "strict": true,
            "additionalProperties": false
          }
        }
      },
      "strict": true,
      "additionalProperties": false
    },
    "data": {
      "description": "This is the list of strings to be classified",
      "type": "array",
      "maxItems": 9999,
      "items": {
        "type": "string",
        "maxLength": 280
      }
    }
  },
  "strict": true,
  "additionalProperties": false
}

You can use a validator such as the one found at https://www.jsonschemavalidator.net/ to check your JSON

Example of a valid JSON:

{
 "config": {
   "user": "user_name",
   "password": "123456",
   "job_name": "New Job",
   "language": "english",
   "no_times_to_verify": 3,
   "tags": [
     {
       "tag_name": "positive",
       "tag_desc": "positive comments"
     },
     {
       "tag_name": "negative",
       "tag_desc": "negative comments"
     }
   ]
 },
 "data": [
   "It is really easy to create new jobs",
   "This is the second line of text to be classified."
 ]
}

To download the data generated by one of your jobs, POST a JSON file to the following endpoint:

https://duke.pollstr.io/downloadDataAPI/

The following is the JSON schema for this file:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://duke.pollstr.io/downloadDataAPI/",
  "title": "Job data download",
  "description": "This file should be posted in order to retreive the labeled data from a job. Note that it will only return the labels generated up to the moment when the request is made.",
  "type": "object",
  "properties": {
    "user": {
      "description": "Username for pollstr.io",
      "type": "string"
    },
    "password": {
      "description": "Password for your pollstr.io account",
      "type": "string"
    },
    "job_name": {
      "description": "Name of the job you want to download data from. It must be one of your previously created jobs.",
      "type": "string",
      "maxLength": 40
    }
  },
  "strict": true,
  "additionalProperties": false
}

You can use a validator such as the one found at https://www.jsonschemavalidator.net/ to check your JSON

Example of a valid JSON:

{
  "user": "user_name",
  "password": "123456",
  "job_name": "New Job"
}

POST a JSON file to the following endpoint:

https://duke.pollstr.io/changeStatusAPI/

The following is the JSON schema for this file:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://duke.pollstr.io/changeStatusAPI",
  "title": "Change job status",
  "description": "This file is used to change the status of  a job from running to stopped and vice versa. This will not erase a job or its data",
  "type": "object",
  "properties": {
    "user": {
      "description": "Username for pollstr.io",
      "type": "string"
    },
    "password": {
      "description": "Password for your pollstr.io account",
      "type": "string"
    },
    "job_name": {
      "description": "Name of the job you want to download data from. It must be one of your previously created jobs.",
      "type": "string",
      "maxLength": 40
    },
    "status": {
      "description": "",
      "type": "string",
      "enum": ["start", "stop"]
    }
  },
  "strict": true,
  "additionalProperties": false
}

You can use a validator such as the one found at https://www.jsonschemavalidator.net/ to check your JSON

Example of a valid JSON:

{
  "user": "user_name",
  "password": "123456",
  "job_name": "New Job",
  "status": "stop"
}