# ⚡ Bulk Request API

The Bulk API is useful when you have a large number of requests to process, which you want to process as fast as possible, with the results to be saved to your own (AWS S3-compatible) storage.

The Bulk API works asynchronously, meaning that you can submit a large number of requests, and once we are done processing all of your requests, we will notify you through an optional Webhook once completed.

Since this works asynchronously, we store the results of your requests on your provided AWS S3-compatible storage. This means that you can retrieve the results at any time, and you can also store the results for as long as you want.

In order to use the SpeedyShot Bulk API, you will need:

• An AWS S3 compatible storage
• IAM Access Keys for the S3 storage
• SpeedyShot API Key
• (Optional) Webhook to be notified when the processing is done

The SpeedyShot Bulk API service is located at

https://service.speedyshot.com/api/bulk

This service only accepts POST requests, as this is a safer way to work with API keys.

The service require authentication in order to be used. We accept API keys as a form of authentication, to be set in the header of your request.

Authorization

The Bulk API request body is a JSON object, containing the following fields:

• config: An object containing the global configuration. Any configuration set here will be copied for the individual request items
• items: An array of objects, each containing a single request to be processed. Any configuration set here will override the above global configuration. For syntax, see the Single Request API Options.

{
    "config": {
        // Mandatory storage configuration for Bulk API
        "storageAuthKey": "<Your AWS S3 Access Key>",
        "storageAuthSecretKey": "<Your AWS S3 Secret Key>",
        "storageBucket": "<Your AWS S3 Bucket Name>",
        ... // Optionally more parameters (see single-request API Options)
    },
    "items": [
        {
            url: "https://example.com",
            storageFilePath: "myFolder/myFile.jpg" // Optional, if not set:
            // the file will be stored in the root of the bucket
            ... // All single request options are supported
        }
    ]   
}

Our API's response code follows the most common standards. Below is an overview of the codes and their meanings.

• HTTP 200: Successful request
• HTTP 401: API Key was not accepted
• HTTP 403: User account is disabled, or free account is out of credits
• HTTP 500: An error occurred processing your request. See the response.serviceErrorMessage field.
• HTTP 502: The service is not reachable, and we are probably provisioning an extra service to handle the extra load.

The response contains data in 3 locations:

• HTTP Status Code
• HTTP Headers
• HTTP Response Body (always application/json formatted)

Any request to SpeedyShot will contain the following headers:

x-credits-remaining-before

x-credits-refill-timestamp

x-api-call-id

x-ratelimit-limit

x-ratelimit-remaining

The response body will include some information on your submitted request, you can find the exact structure in the below example.

{
  "information": "Bulk request sent for processing.",
  "warning": "Bulk requests cannot be stopped once sent for processing.",
  "itemsSentForProcessing": 19,
  "creditsRemainingAfterProcessing": 184923
}