HTTP API Structure

Automation Cloud offers an HTTP API to interact with various components.

The base subdomain is https://api.automationcloud.net

You must provide Content-Type: application/json header when you send JSON data to the API.

Authentication

The majority of endpoints require authentication.

Authentication to the API happens via the basic HTTP authentication. Provide your app secret key as the username value. You don't need to provide a password.

curl 'https://api.automationcloud.net/services'
  -u '$APP_SECRET_KEY:'
  -H 'Content-Type: application/json'

If you chose to authenticate with an Authorization: Basic <credentials> header, provide the credentials as the Base64 encoding of the $APP_SECRET_KEY:.

curl 'https://api.automationcloud.net/services'
  -H "Authorization: Basic QVBJX0tFWTo="
  -H 'Content-Type: application/json'

TIP

You can view and manage your apps in the Automation Cloud Dashboard.

WARNING

Each app is associated with a single valid app secret key. Do not expose the secret anywhere, as it provides access to many endpoints on behalf of your app. Please regenerate the secret if you lose or compromise it – you can do so via the Automation Cloud Dashboard.

Job access token

While app secret should never be visible to an end-user, we provide a less sensitive token that you can use on the client-side. A job access token is a Basic username value that is valid in the scope of the job. No password is required. Once you have a unique job id, call the job's End User endpoint to obtain a job access token. Look for the token value in the response.

JSON Output

All responses from the API will be returned as JSON, apart from exceptional cases (such as iframe content endpoints).

HTTP Methods

The Automation Cloud API uses RPC-based conventions. As such, only three request methods are supported:

GET
POST
OPTIONS

UUID Format

Where resource IDs are present in the response body or as a parameter in the path or query, these will be UUIDv4 compliant.

Errors

We use conventional HTTP response codes to indicate the success or failure of an API request.

In general,

• 2xx – means success.
• 4xx – shows an error that failed given the information provided.
• 5xx – indicates an error with Automation Cloud servers.

WARNING

Some 4xx errors include additional information, e.g. an error code that briefly explains the problem. However, this part of API is a work in progress. We don't recommend relying on the format of these errors yet.

Example 400 responses

Retrieve the Service error

Attempt to fetch an Automation Cloud service using an invalid id.

{
    "object": "error",
    "code": "badRequest",
    "name": "RequestParametersValidationError",
    "message": "Invalid request parameters:\n    - /serviceId must match format \"uuid\"",
    "details": {
        "messages": ["/serviceId must match format \"uuid\""]
    }
}

Provide additional input error

Attempt to supply a job input that is already provided.

{
    "object": "error",
    "code": "badRequest",
    "name": "RecordNotUniqueError",
    "message": "RecordNotUniqueError",
    "details": {
        "keys": ["jobId", "key"]
    }
}

Example 401 response

Attempt to use an invalid auth token.

{
    "error": "Unauthorized"
}

Example 403 response

Create a Job error

Attempt to create a job using the app secret key of a client that is not authorised to make jobs on the given Automation Cloud service.

{
    "object": "error",
    "code": "forbidden",
    "name": "ForbiddenError",
    "message": "ForbiddenError",
    "details": {
        "action": "create",
        "object": {
            "object": "client",
            "id": "4d70b918-03e6-417c-b170-72581b13632d",
            "name": "robot-school@ub.io"
        },
        "subject": {
            "serviceId": "bd80b73a-af55-4087-a5d4-91f6c8619948"
        }
    }
}

Example 404 response

Retrieve the Service error

Attempt to fetch an Automation Cloud service that is not available for the client or doesn't exist.

{
    "object": "error",
    "code": "notFound",
    "name": "RecordNotFoundError",
    "message": "RecordNotFoundError",
    "details": {
        "table": "services"
    }
}