FORMAT: 1A
HOST: https://api.cloudsight.ai/v1

# CloudSight API

The CloudSight API is a simple REST API for understanding your images.
Send us an image and we will return a description of its contents.

## Authentication

You can authenticate by one of two ways to the CloudSight API: OAuth1-Simple with key and secret, or simple key-based
authentication.  Your API key is very important and identifies any request as yours, so be sure to keep it secret.  We
recommend using HTTPS for communications with the API, otherwise your key will be sent in plain text over the internet,
which is insecure.

### Simple Key-Based

On each request, include the following header, and replace `[key]` with the key provided for your account.

```
Authorization: CloudSight [key]
```

### OAuth1 Method

In this method, the client calculates a signature from a key, secret, nonce, URL and parameters included in the request,
and includes the resulting data in the `Authorization` HTTP header.  A full description of OAuth1 is outside the scope
of this document.  Please visit http://tools.ietf.org/html/rfc5849 for more information.

Use the authentication key and secret provided and make sure the `image` parameter is excluded from the
signature calculation.  A detailed description of how to calculate the OAuth header is described in the following
section.

## SDKs

CloudSight has a number of different SDKs to make using the API easy in your language of choice.

**Ruby**: https://github.com/cloudsight/cloudsight-ruby

**Objective C**: https://github.com/cloudsight/cloudsight-objc

**Python**: https://github.com/cloudsight/cloudsight-python

**Elixir**: https://github.com/cloudsight/cloudsight_elixir

**Go**: https://github.com/cloudsight/cloudsight-go

## Images Collection [/images]

### Send an Image for Identification [POST]

Send an image by using an HTTP POST request on the endpoint `/images` either as a multipart file upload, a base64 encoded image or a remote image url.
These three cURL requests demonstrate the three possible ways of sending an image.

1 - Multipart File

```bash
curl -X POST \
  https://api.cloudsight.ai/v1/images \
  -H 'authorization: CloudSight [key]' \
  -H 'cache-control: no-cache' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F image=@/path/to/image.jpg
```

2 - Base64 Encoded (we do not recommend this for anything other than very small images)

```bash
curl -X POST \
  https://api.cloudsight.ai/v1/images \
  -H 'authorization: CloudSight [key]' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "image": "data:image/png;base64,R0lG0dJDAhgbn...etc"
}'
```

3 - Remote Image URL

```bash
curl -X POST \
  https://api.cloudsight.ai/v1/images \
  -H 'authorization: CloudSight [key]' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
    "remote_image_url": "http://englishbookgeorgia.com/blogebg/wp-content/uploads/2015/08/husky.jpg"
}'
```

Any of these methods work, but only one can be used per request. Note that the first two have a parameter of `image` while the last has a parameter of `remote_image_url`.

If a URL is sent, the URL must return a 200 response. Any non-200 response will result in an error, including redirect
responses (e.g. 3xx status).

The focus parameters accept the point, using North-West gravity (0,0 corresponds to the upper-left corner), for which to
place a highlight of attention on the image. In the event there are many identifiable objects in the image, this
attempts to place importance on the ones closest to the focal point. You may specify a focal point in terms of relative
coordinates (0.0 through 1.0) or absolute coordinates (i.e. a 400x400 image would have 0 through 400 for each axis).

Once the image request has been received, a response will be returned containing either a success or error message. If
the request is successful, you will receive a `url` parameter containing a URL to the image as stored on our service, and
a token for the image, which you can use to retrieve the resulting annotation data in the `/images/:token` endpoint.

Note: We recommend an image resolution no higher than 1024x, and a JPEG compression level between 5-8. We resize images
internally otherwise, and it could slow down the request process.

+ Request (application/json)

  + Headers

              Authorization: CloudSight [key]

  + Attributes
      + image (string) - Filepath - if you wish to upload a file the request must be multipart form encoded
      + remote\_image\_url (string) - Url of image. If you are sending the URL the request can be JSON.
      + locale: `en_US` (string) - The locale of the request
      + language: `en_US` (string) - The language that the response should be returned in
      + device\_id (string) - A unique ID generated for the device sending the request. We recommend generating a UUID.
      + latitude (string) - Geolocation information for additional context
      + longitude (string) - Geolocation information for additional context
      + altitude (string) - Geolocation information for additional context
      + ttl (number) - Deadline in seconds before expiration
      + focus_x (number) - Focal point on image (x-coordinate) for specificity
      + focus_y (number) - Focal point on image (y-coordinate) for specificity

   + Body

                {
                    "remote_image_url": "https://example_images/logo.png"
                }

+ Response 201 (application/json)

    + Headers

            X-CloudSight-CreditBalance: 1
            X-CloudSight-Overage: 0

    + Body

            {
                "url": "https://images.cloudsightapi.com/uploads/image_request/image/19/19404/19404152/Image.jpg",
                "token": "AJKAWHKGLjqMd9KDNIXQfg"
            }

+ Response 422 (application/json)

        {
          "error" : {
              "image" : ["can't be blank"]
          }
        }


## Image [/images/{token}]

### View an Image Response [GET]

This endpoint retrieves the result of the image you identified. Supply the token received from the `/images` endpoint in
the `/images/[token]` URL, replacing [token]. CloudSight will return one of several responses depending on the status of
the identification.

Identification of an image can take several seconds. We recommend your application "sleep" for 5 seconds before polling the
API using the endpoint above for the response. If you receive a response with `"status": "not completed"`, we suggest polling
the API every second until a "completed" response is received.

#### Skip Reasons
This endpoint can also return a result with a status of `skipped` and a `reason` the image was not processed. Reasons which
an image may be `skipped` include:

- `offensive` - The image was found to be offensive in nature.
- `blurry` - The image was too blurry to be identified.
- `dark` - The image was too dark to be identified.
- `bright` - The image was too bright to be identified.
- `unsure` - The image was unable to be identified for unknown reasons.
- `close` -  The image was not properly processed.

When a response is returned with a `skipped` reason of either `unsure` or `close`, it is a
best practice to attempt a single [repost](http://docs.cloudsight.apiary.io/#reference/0/repost/repost-an-image)
of the image token.

#### Flags
This endpoint can also return flags which can further indicate attributes of an image. A key of `flags` containing an array
of values include:

- `adult` - The image is considered "adult" in nature, usually non-pornographic nudity.

+ Parameters

    + token: [token] (string) - Token returned by your POST to the images endpoint

+ Request

  + Headers

              Authorization: CloudSight [key]


+ Response 200 (application/json)

        {
          "token" : "WySLTJWESPTtt6v0oBmzKf",
          "url" : "http://.../your_headphones_image.jpg",
          "ttl" : 60,
          "status" : "completed",
          "name" : "red beats by dre headphones",
          "flags" : ["adult"]
        }

+ Response 200 (application/json)

        {
          "token" : "WWfqDSw6Ui1rtNDYlVvX2w",
          "url" : "http://.../blurry_image.jpg",
          "ttl" : 60,
          "status" : "skipped",
          "reason" : "blurry"
        }

## Repost [/images/{token}/repost]
### Repost an Image [POST]

If an image request has timed out; `{ "status" : "timeout" }`, you may re-post the request by indicating the original
token and the /repost path. For example, if an image request was received successfully and a token `example\_token` was
given, and had subsequently timed out, you can repost the image with this endpoint.

+ Parameters

    + token (string) - Token returned by your POST to the images endpoint

+ Request

  + Headers

              Authorization: CloudSight [key]

+ Response 201 (application/json)

        {
          "status" : "not completed",
          "url" : "http://.../your_headphones_image.jpg",
          "token" : "WySLTJWESPTtt6v0oBmzKf"
        }
