NAV Navbar
Logo
cURL Ruby

Introduction

Welcome to the Hitblocks API documentation! Our API is REST based. That means predictable resource-oriented URLs, which return HTTP response codes to indicate API errors.

Responses are given in JSON format, which return both errors and data requested.

Authentication

To authorize, use this code:

require 'hitblocks'

api = Hitblocks.api_key = "8641fb38-294a-41d9-9591-3449dfd99910"
# With shell, you can just pass the correct header with each request
curl "https://api.hitblocks.ai/v1/hitblocks"
  -u 8641fb38-294a-41d9-9591-3449dfd99910

Make sure to replace 8641fb38-294a-41d9-9591-3449dfd99910 with your API key.

Authentication is done using an API secret key in a given request. Manage API keys from your dashboard. API keys allow access to all functions of your account and should be kept secret. Do not put keys on publicly accessable Github repositories or in client-side code.

Authentication is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

Hitblocks expects for the API key to be included in all API requests to the server in a header that looks like the following:

All API requests will be made of HTTPS. Calls over plain HTTP will fail. API requests without authentication will also fail.

Errors

Hitblocks uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in 2xx range are successful, codes in the 4xx range indicate a user based error, and codes in 5xx range indicate an error on Hitblock’s servers.

Error codes

The Hitblocks API uses the following error codes:

Error Code Meaning
200 - OK Everything worked as expected
400 - Bad Request Your request sucks
401 - Unauthorized Your API key is wrong
403 - Forbidden The resource requested is not available for your account
404 - Not Found The requested resource could not be found
405 - Method Not Allowed You tried to access a resource with an invalid method
406 - Not Acceptable You requested a format that isn’t JSON
410 - Gone The resource requested has been removed from our servers
429 - Too Many Requests You’re requesting too many resources at once! Slow down!
500 - Internal Server Error We had a problem with our server. Try again later.
503 - Service Unavailable We’re temporarily offline for maintenance. Please try again later.

Error types

There is also a body response that contains more detailed information about specific errors that you can look up here.

Errors

Types Meaning
api_connection_error Failure to connect to Hitblock’s API.
api_error API errors cover any other type of problem (e.g., a temporary problem with Hitblock’s servers) and are extremely uncommon.
authentication_error Failure to properly authenticate yourself in the request.
invalid_request_error Invalid request errors arise when your request has invalid parameters.
rate_limit_error Too many requests hit the API too quickly.
validation_error Errors triggtered by our interfaces when failing to validate incoming properties.

Handling errors

Our API libraries will try to raise exceptions for any of the reasons above, but we recommend you write code that handles all possible API exceptions.

Hitblocks

Get Hitblock

require 'hitblocks'

Hitblocks.api_key('8641fb38-294a-41d9-9591-3449dfd99910')

Hitblocks::Hitblocks.get(<ID>)
curl "https://api.hitblocks.ai/v1/hitblock/<ID>" \
  -u 8641fb38-294a-41d9-9591-3449dfd99910

The above command returns JSON structured like this:

{
  "object": "hitblock",
  "id": 4,
  "type": "image-transcription",
  "title": "Receipt Transcription",
  "description": "for transcribing bbq shop receipts"
  "created": 1495230848,
  "cost_per_item": 0.10,
  "total_spent": 2.00,
  "workers_per_item": 1,
  "currency": "usd"
}

This endpoint retrieves a specific hitblock.

HTTP Request

GET https://www.hitblocks.ai/v1/hitblock/<ID>

URL Parameters

Parameter Description
ID The ID of the hitblock to retrieve

List Hitblocks

require 'hitblocks'

Hitblocks.api_key('8641fb38-294a-41d9-9591-3449dfd99910')

Hitblocks::Hitblocks.list
curl "https://api.hitblocks.ai/v1/hitblocks" \
  -u 8641fb38-294a-41d9-9591-3449dfd99910

The above command returns JSON structured like this:

{
  "object": "list",
  "url": "/v1/hitblocks",
  "data": [
    {
      "object": "hitblock",
      "id": 4,
      "type": "image-transcription",
      "title": "Receipt Transcription",
      "description": "for transcribing bbq shop receipts"
      "created": 1495230848,
      "cost_per_item": 0.10,
      "workers_per_item": 1,
      "currency": "usd"
    },
    {
      "object": "hitblock",
      "id": 5,
      "type": "image-transcription",
      "title": "Handwriting Transcription",
      "description": "for transcribing notes into digital copies"
      "created": 1495230848,
      "cost_per_item": 0.25,
      "workers_per_item": 1,
      "currency": "usd"
    }
  ]
}

This endpoint retrieves all hitblocks.

HTTP Request

GET https://api.hitblocks.ai/v1/hitblocks

Items

List All Items

require 'hitblocks'

Hitblocks.api_key('8641fb38-294a-41d9-9591-3449dfd99910')

hitblock = Hitblocks::Hitblock.get(<hitblock_id>)
hitblock.items
curl "https://api.hitblocks.ai/v1/hitblock/<hitblock_id>/items" \
  -u 8641fb38-294a-41d9-9591-3449dfd99910

The above command returns JSON structured like this:

{
  "object": "list",
  "url": "/v1/hitblock/<hitblock_id>/items",
  "data": [
    {
      "object": "item",
      "id": 2,
      "type": "image",
      "created": 1495230848,
      "cost": 0.10,
      "currency": "usd",
      "status": "completed",
      "params": {
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg",
        "description": "image of receipt1.jpg"
      },
      "responses": [
        {
          "object": "response",
          "data": {...},
          "approved": "false"
        },
        {
          "object": "response",
          "data": {...},
          "approved": "true"
        }
      ]
    },
    {
      "object": "item",
      "id": 3,
      "type": "image",
      "created": 1495230905,
      "cost": 0.10,
      "currency": "usd",
      "status": "completed",
      "params": {
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg",
        "description": "image of receipt2.jpg"
      },
      "responses": [
        {
          "object": "response",
          "data": {...},
          "approved": "false"
        },
        {
          "object": "response",
          "data": {...},
          "approved": "true"
        }
      ]
    }
  ]
}

This endpoint retrieves all items in a given hitblock.

HTTP Request

GET https://api.hitblocks.ai/v1/hitblock/<hitblock_id>/items

URL Parameters

Parameter Description
hitblock_id The ID of the hitblock to get items from.

Get an Item

require 'hitblocks'

Hitblocks.api_key('8641fb38-294a-41d9-9591-3449dfd99910')

Hitblocks::Item.get(item_id)
curl "https://api.hitblocks.ai/v1/item/<ID>" \
  -u 8641fb38-294a-41d9-9591-3449dfd99910

The above command returns JSON structured like this:

{
  "object": "item",
  "id": 2,
  "type": "image",
  "created": 1495230848,
  "cost": 0.10,
  "currency": "usd",
  "status": "completed",
  "params": {
    "image_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg",
    "description": "image of receipt1.jpg"
  },
  "responses": [
    {
      "object": "response",
      "data": {...},
      "approved": "true"
    },
    {
      "object": "response",
      "data": {...},
      "approved": "false"
    }
  ]
}

This endpoint retrieves a specific item.

HTTP Request

GET https://www.hitblocks.ai/v1/item/<ID>

URL Parameters

Parameter Description
ID The ID of the item to retrieve

Create an Item

require 'hitblocks'

Hitblocks.api_key('8641fb38-294a-41d9-9591-3449dfd99910')

hitblock = Hitblocks::Hitblock.get(<hitblock_id>)

Hitblocks::Item.create(
    :type => "image",
    :hitblock => hitblock,
    :image_url => "http://www.images.com/my-image.jpg",
    :description => "My image from personal website"
)
curl "https://api.hitblocks.ai/v1/hitblocks/<hitblock_id>/items" \
  -u 8641fb38-294a-41d9-9591-3449dfd99910 \
  -d type="image" \
  -d image_url="http://www.images.com/my-image.jpg" \
  -d description="My image from personal website"

The above command returns JSON structured like this:

{
  "object": "item",
  "id": 3,
  "type": "image",
  "created": 1495231005,
  "cost": 0.10,
  "currency": "usd",
  "status": "completed",
  "params": {
    "image_url": "http://www.images.com/my-image.jpg"
    "description": "My image from personal website"
  },
  "responses": {
  }
}

This endpoint creates a specific item.

HTTP Request

POST https://www.hitblocks.ai/v1/hitblocks/<hitblock_id>/items

Arguments

Arguments Required Description
type yes The type of item, for verification against allowed hitblock inputs.
hitblock_id yes the ID of the hitblock the item should be placed in.
image_url yes a parameter for the “image” item that points to the hosted image.
description no an optional string. Useful for displaying information to users.

Delete an Item

require 'hitblocks'

Hitblocks.api_key('8641fb38-294a-41d9-9591-3449dfd99910')

item = Hitblocks::Item.get(<ID>)
item.delete

curl "https://api.hitblocks.ai/v1/item/<ID>" \
  -u 8641fb38-294a-41d9-9591-3449dfd99910 \
  -X DELETE

The above command returns JSON structured like this:

{
  "deleted": true,
  "id": "<ID>"
}

This endpoint deletes a specific item.

HTTP Request

DELETE https://www.hitblocks.ai/v1/item/<ID>

URL Parameters

Parameter Description
ID The ID of the item to be deleted.

Post an Item

require 'hitblocks'

Hitblocks.api_key('8641fb38-294a-41d9-9591-3449dfd99910')

item = Hitblocks::Item.get(<ID>)
item.post

curl "https://api.hitblocks.ai/v1/item/<ID>/post" \
  -u 8641fb38-294a-41d9-9591-3449dfd99910 \

The above command returns JSON structured like this:

{
  "object": "HIT",
  "url": "www.google.ca",
  "service": "AMT",
  "status": "published",
  "created": 1495230848,
  "item": {
    "object": "item",
    "id": 2,
    "type": "image",
    "created": 1495230848,
    "cost": 0.10,
    "currency": "usd",
    "status": "published",
    "params": {
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/ReceiptSwiss.jpg",
      "description": "image of receipt1.jpg"
    },
    "responses": {
    }
  }
}

This endpoint posts a specific item to crowdsourced workers on Amazon Mechanical Turk

HTTP Request

POST https://www.hitblocks.ai/v1/item/<ID>/post

URL Parameters

Parameter Description
ID The ID of the item to be deleted.