Get the data for the tokens given in the request body. Any JSON values that are not reference tokens will be returned as is. No more than 1024 values are accepted in a request. If any token is associated with data greater than 3kb, the value will be null in the response. If the total size of the request, after ignoring single values that overflow, is greater than 500kb, the request will be rejected with a 509 status code.

/api/v1/batch

Request

Field

Type

Description

Authorization

String

ALTR API's authorization protocol relies on a properly formatted authorization header. The accepted format is: "ALTR " + api_key + ":" + signature. signature is a base64-encoded, SHA-256 hash that uses the API key's secret as the key for the hash function. The payload being hashed must follow the format: HTTP-METHOD + "\n" + RESOURCE + "\n" + DATE + "\n". DATE must match X-ALTR-DATE, and RESOURCE must be empty for a POST request. An example payload for a POST request is: "POST\n\n01-01-1970 00:00:00\n"

X-ALTR-DATE

Date

The datetime used in the Date signature. If this is more than 15 minutes past the server's internal clock, the request will be rejected.

Content-Type

String

must be application/json

Response

Field

Type

Description

X-OVERFLOW-DATA

String

If any token is over 3kb, or the entire batch is over 500kb this flag will be set and the tokens that overflowed will be returned as null.

date = new Date();
payload = 'PUT\n\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
    "X-ALTR-DATE": date,
    "Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET)),
    "Content-Type": "application/json"
}
{
    "X-OVERFLOW-DATA": true
}
{
    "id": "1"
    "key1": "token1",
    "key2": "token2"
}

200

Field

Type

Description

body

json

On success, all tokens given in the request will be replaced with the data associated. All non-tokens are given back. If the data for any token is greater than 3kb, the X-Overflow-Data header will be set to true and the value associated with the key will be null.

HTTP/1.1 200 OK
{
  "id": "1",
  "key1": <data for token1>,
  "key2": <data for token2>
}

Error Codes

Code

Name

Description

400

bad_request

Invalid JSON detected.

401

unauthorized

The API key could not be authenticated.

403

forbidden

API key does not have read permissions.

404

resource_not_found

The requested resource could not be found.

503

internal_error

The web server encountered an unexpected error.

509

bandwith

Limit Exceeded Request exceeded 500kb limit. X-Overflow-Data header will be set to true.

HTTP/1.1 503 Internal Server Error
{
  "success": false,
  "response": {
      "error_type": "internal_error",
      "error_message": "Unable to process request at this time."
  }
}
HTTP/1.1 400 Bad Request
{
  "success": false,
  "response": {
      "error_type": "bad_request",
      "error_message": "Invalid JSON detected. Failed unique key check"
  }
}
HTTP/1.1 401 Authentication Required
  {
    "success": false,
    "response": {
        "error_type": "unauthorized",
        "error_message":  "API key must be included in header."
    }
}
HTTP/1.1 403 Forbidden
{
  "success": false,
  "response": {
      "error_type": "forbidden",
      "error_message":  "API key does not have read permissions."
  }
}
HTTP/1.1 404 Not Found
{
  "success": false,
  "response": {
      "error_type": "resource_not_found",
      "error_message":  "The following tokens could not be found: "
  }
}