NAV
curl Node.js

Introduction

Welcome to the elastic.io REST API!

Authentication

You authenticate to the elastic.io API by providing your API key in the request.

Authentication to the API occurs via HTTP Basic Auth. Provide your email as the basic auth username and API key as the password.

curl https://api.elastic.io/v1/users \
   -u {EMAIL}:{APIKEY}
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

Accounts

Get user’s accounts

Example Request:

curl https://api.elastic.io/v1/accounts/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.accounts.list()
    .then(function(accounts) {
        // do something with the accounts
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id":"55083c567aea6f030000001a",
        "name":"My Component account",
        "keys": {
            "oauth": {
                "key": "some key"
            }
        }
    }
]

This endpoint retrieves list of user’s accounts

HTTP Request

GET https://api.elastic.io/v1/accounts/

Returns

Returns a list of accounts if the call succeeded.

Get user’s account

Example Request:

curl https://api.elastic.io/v1/accounts/{ACCOUNT_ID}/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.accounts.retrieve({ACCOUNT_ID})
    .then(function(account) {
        // do something with the account
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "55083c567aea6f030000001a",
    "name": "My Component account",
    "type": "55ffca6ecc04c20600000001",
    "keys": {
        "oauth": {
            "key": "some key"
        }
    }
}

This endpoint retrieves one of user’s accounts

HTTP Request

GET https://api.elastic.io/v1/accounts/{ACCOUNT_ID}/

URL Parameters

Parameter Description
ACCOUNT_ID The ID of the account

Returns

Returns an account object if the call succeeded.

Add new account

Example Request:

 curl https://api.elastic.io/v1/accounts/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
      "name": "My Component account",
      "type": "{COMPONENT_ID}",
      "keys": {
         "oauth": {
            "key": "some key"
      }
   }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.accounts.create({
    "name": "My Component account",
    "type": "{COMPONENT_ID}",
    "keys": {
        "oauth": {
            "key": "some key"
        }
    }
}).then(function(account) {
    // do something with the account
});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "54982ee6bdf2a2030000000f",
  "name": "My Component account",
  "type": "55ffca6ecc04c20600000001",
  "keys": {
    "oauth": {
      "key": "some key"
    }
  }
}

This endpoint adds new key to list of user’s keys

HTTP Request

POST https://api.elastic.io/v1/accounts/

Arguments

Parameter Required Description
name no Account name
type no The component id this account is for
keys no An object which represents component’s configuration (OAuth keys, etc.)

Returns

Returns account object if the call succeeded.

Modify user’s account

Example Request:

curl https://api.elastic.io/v1/accounts/{ACCOUNT_ID}/ \
   -u {EMAIL}:{APIKEY} \
   -X PUT \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
      {
          "name": "New account name"
      }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.accounts.update({ACCOUNT_ID}, {
    "name": "New account name"
});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "55083c567aea6f030000001a",
    "name": "New account name",
    "type": "55ffca6ecc04c20600000001",
    "keys": {
        "oauth": {
            "key": "some key"
        }
    }
}

This endpoint modifies user’s account

HTTP Request

PUT https://api.elastic.io/v1/accounts/{ACCOUNT_ID}/

URL Parameters

Parameter Description
ACCOUNT_ID The ID of the account

Arguments

Parameter Required Description
name no Account name
type no The component id this account is for
keys no An object which represents component’s configuration (OAuth keys, etc.)

Returns

Returns a modified account object if the call succeeded.

Components

Retrieve private components

Example Request:

curl https://api.elastic.io/v1/components/mine \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.components.mine()
    .then(function(components) {
        // do something with components
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "components": [
    {
      "data": {
        "title": "Component title",
        "description": "Description",
        "icon": "<String>",
        "credentials": {
          "fields": {
            "name": {
              "viewClass": "TextFieldView",
              "required": true,
              "label": "Your name"
            }
          }
        },
        "triggers": {
          "select": "<Triggers Object>"
        },
        "actions": {
          "update": "<Actions Object>"
        }
      },
      "repo_id": "MONGO_ID"
    }
  ]
}

This endpoint retrieves list of user’s components. More details you can find here.

HTTP Request

GET https://api.elastic.io/v1/components/mine

Returns

Returns repositories metadata object if the call succeeded.

Response fields

Field Type Description
icon String Icon in base64
triggers Object <Triggers Object>
actions Object <Actions Object>

Retrieve public components

Example Request:

curl https://api.elastic.io/v1/components/public \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.components.public()
    .then(function(components) {
        // do something with components
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "components": [
    {
      "data": {
        "title": "Timer",
        "description": "Timer",
        "icon": "<String>",
        "fields": {
          "interval": {
            "label": "Interval",
            "model": {
              "day": "Every Day",
              "hour": "Every Hour",
              "minute": "Every Minute"
            },
            "prompt": "Please select an interval",
            "required": true,
            "viewClass": "SelectView"
          }
        },
        "triggers": {
          "timer": {
            "title": "Timer",
            "main": "./timer.js",
            "type": "polling",
            "metadata": {
              "out": {
                "properties": {
                  "fireTime": {
                    "format": "date-time",
                    "required": true,
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        }
      },
      "repo_id": "MONGO_ID"
    }
  ]
}

This endpoint retrieves list of public components More details you can find here.

HTTP Request

GET https://api.elastic.io/v1/components/public

Returns

Returns repositories metadata object if the call succeeded.

Response fields

Field Type Description
icon String Icon in base64
triggers Object <Triggers Object>
actions Object <Actions Object>

Retrieve an single component descriptor

Example Request:

curl https://api.elastic.io/v1/components/{COMPONENT_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.components.retrieve({COMPONENT_ID})
    .then(function(components) {
        // do something with components
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "repo_id": "55828f5a630d500800000003",
  "data": {
    "title": "mock component",
    "description": "mock",
    "credentials": {
      "fields": {
        "name": {
          "label": "Your name",
          "required": true,
          "viewClass": "TextFieldView"
        }
      }
    },
    "triggers": {
      "getHello": {
        "main": "./lib/triggers/getHello.js",
        "type": "polling",
        "title": "Query Hello",
        "metadata": {
          "out": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string",
                "required": false,
                "title": "Hello string"
              }
            }
          }
        }
      }
    },
    "actions": {
      "updateHello": {
        "main": "./lib/actions/updateHello.js",
        "title": "Update Hello",
        "fields": {
          "dynamicSelect": {
            "viewClass": "SelectView",
            "prompt": "Select your value",
            "label": "Value",
            "required": false,
            "model": "getModel"
          }
        },
        "dynamicMetadata": true
      }
    },
    "language": "nodejs",
    "sailor_version": "0.0.4",
    "icon": "iVBORw0KGgoAAAANSUhEAAASUVORK5CYII="
  },
  "name": "mock-component",
  "team": "elasticio"
}

This endpoint retrieves an information about single component by it’s ID More details you can find here.

HTTP Request

GET https://api.elastic.io/v1/components/{COMPONENT_ID}

Returns

Returns repositories metadata object if the call succeeded.

Response fields

Field Type Description
repo_id String ID of the component
data Object A component descriptor, see <here>
name String A name of the component repository
team String A name of the component repository team

Repositories

Get user’s repositories

Example Request:

curl https://api.elastic.io/v1/repos/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.repos.list()
    .then(function(repos) {
        // do something with the repos
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "555c5ade13c2298a9d32fe67",
    "name": "testrepo",
    "team_id": "5538bc1c9c0f0522391900d4"
  }
]

HTTP Request

GET https://api.elastic.io/v1/repos/

Returns

Returns repositories metadata object if the call succeeded.

Get user’s repository

Example Request:

curl https://api.elastic.io/v1/repos/{REPO_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.repos.retrieve({REPO_ID})
    .then(function(repo) {
        // do something with the repo
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "id": "555c5ade13c2298a9d32fe67",
    "name": "testrepo",
    "team_id": "5538bc1c9c0f0522391900d4"
  }

HTTP Request

GET https://api.elastic.io/v1/repos/{REPO_ID}

URL Parameters

Parameter Required Description
REPO_ID yes repository id

Returns

Returns repositories metadata object if the call succeeded.

Create repository

Example Request:

curl https://api.elastic.io/v1/repos/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' -d '
   {
       "name": "My Repo"
   }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.repos.create({
    "name": "My Repo"
}).then(function(repo) {
    // do something with the repo
 });

Example Response:

HTTP/1.1 201 OK
Content-Type: application/json

{
    "name":"repository name",
    "id": "repo_id",
    "team_id": "team_id",
     "is_public": false
}

This endpoint creates new custom repository

HTTP Request

POST https://api.elastic.io/v1/repos/

Parameter Required Description
name no repository name
team_id no team this repo will belong to

Returns

Returns repositories metadata object if the call succeeded.

Delete repository

Example Request:

curl https://api.elastic.io/v1/repos/{REPO_ID} \
   -u {EMAIL}:{APIKEY} \
   -X DELETE \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.repos.delete({REPO_ID});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

This endpoint delete repository

HTTP Request

DELETE https://api.elastic.io/v1/repos/{ID}

URL Parameters

Parameter Required Description
REPO_ID yes repository id

Get env vars

Example Request:

curl https://api.elastic.io/v1/repos/{REPO_ID}/env/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.repos.retrieveEnvVars({REPO_ID})
    .then(function(vars) {
        // do something with the env vars
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "API_KEY": "key",
    "API_SECRET": "secret"
}

HTTP Request

GET https://api.elastic.io/v1/repos/{REPO_ID}/env/

URL Parameters

Parameter Required Description
REPO_ID yes Repository ID

Returns

Returns environment variables of repository if the call succeeded.

Modify env vars

Update env vars for repository. You can update existing env vars by setting them again, and remove by setting it to NULL.

Example Request:

curl https://api.elastic.io/v1/repos/{REPO_ID}/env/ \
   -X PUT \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' -d '
   {
       "API_KEY": "new_key",
       "API_SECRET": "new_secret"
   }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.repos.updateEnvVars({REPO_ID}, {
    "API_KEY": "new_key",
    "API_SECRET": "new_secret"
});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "API_KEY": "new_key"
}

HTTP Request

PUT https://api.elastic.io/v1/repos/{REPO_ID}/env/

URL Parameters

Parameter Required Description
REPO_ID yes Repository ID

Returns

Returns updated environment variables of repository if the call succeeded.

Resources

S3: Create a signed url

Example Request:

curl https://api.elastic.io/v1/resources/s3/signed-url \
   -X POST  \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.resources.s3
    .createSignedUrl()
    .then(function(result) {
        // do something with the result
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "put_url": "https://bucket.region.amazonaws.com/put",
  "get_url": "https://bucket.region.amazonaws.com/get",
  "expires": 18000
}

This endpoint creates a new signed url in S3

HTTP Request

POST https://api.elastic.io/v1/resources/s3/signed-url

Returns

Returns an HTTP 200 in case of successful url creation

Scheduled Executions

A component execution is an asynchronous operation. Upon an client request an execution is scheduled and needs to wait for the next available worker. Once a worker is available the component is executed and the results are sent back to the client. Because the results of an execution cannot be created and returned immediately the client needs to wait and poll for the results.

For more details about asynchronous REST please read RESTful CookBook and A day in the life of - Asynchronous operations in REST.

The following diagram displays the process of component scheduling:

  1. A component execution is scheduled by sending a request to exec/schedule. The API responds with 202 Accepted. The resource in the Location HTTP header is the url to poll for execution results.
  2. The execution results are polled periodically by sending requests to the polling resourceexec/poll/{EXECUTION_ID}. The API responds with 200 OK if the result is not available yet.
  3. Once the result is available the polling resource responds with 303 See Other. The resource in the Location HTTP header is the url to get the results from.
  4. The results are retrieved from exec/result/{EXECUTION_ID}. Please note that the result may be retrieved only once.

Component execution

Schedule a component execution

Example Request:

 curl https://api.elastic.io/v1/exec/schedule \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
      "execution_type": "get_meta_model",
      "action_or_trigger": "put",
      "component": "{CONNECTOR_ID}",
      "account_id": "{ACCOUNT_ID}"
    }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.exec.schedule({
    "execution_type": "get_meta_model",
    "action_or_trigger": "put",
    "component": "{CONNECTOR_ID}",
    "account_id": "{ACCOUNT_ID}"
}).then(function(result) {

    // location contains the url to poll for results
    var location = result.location;
});

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: 'https://api.elastic.io/v1/exec/poll/540492e623773659c5000002'

{
  "message": "ok"
}

Using this endpoint you can schedule a component execution. It responds with the resource to poll on, in order to get the result of the scheduled execution.

HTTP Request

POST https://api.elastic.io/v1/exec/schedule

Parameter Required Description Used in
execution_type yes “get_meta_model”, “select_model” or “verify_credentials” all requests
component yes Specifies id of the connector to be executed all requests
account_data yes Account data for validation verify_credentials
action_or_trigger yes The name of action or trigger from connector get_meta_model, select_model
account_id yes Account id get_meta_model, select_model
model_method yes Name of the method from action or trigger to execute select_model
cfg no Object with additional parameters get_meta_model, select_model

Returns

Responds with 202 Accepted and a ‘Location’ header. The 'Location’ header specifies a resource to poll on until the execution result is ready.

Poll execution result status

Example Request:

curl https://api.elastic.io/v1/exec/poll/{EXECUTION_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.exec.pollResult({EXECUTION_ID})
    .then(function(response) {
        if (response.ready) {
            // do something with the result
            var result = response.result;
       } else {
            // poll again
       }
    });

Response “In progress”:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Result is not ready yet"
}

Response “Result ready”:

HTTP/1.1 303 See Other
Content-Type: application/json
Location: 'https://api.elastic.io/v1/exec/result/540492e623773659c5000002'

{
  "message": "Ready."
}

This endpoint provides information about the status of a scheduled component execution. Once the execution is done, the endpoint responds with status code 303 and provides a resource to query the result in the 'Location’ header.

HTTP Request

GET https://api.elastic.io/v1/exec/poll/{EXECUTION_ID}

Parameter Required Description
EXECUTION_ID yes The id of a previously scheduled execution

Returns

Status Code Body Header Description
500 {message: 'Internal Server Error'} - An error occured on the server
404 {message: 'Result does not exist.'} - An attempt to poll for a non scheduled execution was made
404 {message: 'Expired.'} - The execution has expired
200 {message: 'Result not ready yet.'} - The execution hasn’t completed yet
303 { message: "Ready." } Location The execution is finished and the result is ready. Resource to get the result is found in the 'Location header’

Get execution result

Example Request:

curl https://api.elastic.io/v1/exec/result/{EXECUTION_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
// As client.exec.pollResult will follow the HTTP 3003 redirect,
// Node.js client does not provide extra functionality to retrieve the results.
// Read the docs of client.exec.pollResult above.

Response “Result available”

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "some": "value"
  }
}

Response “Result not found”

HTTP/1.1 404 Not found
Content-Type: application/json

{
  "message": "Result does not exist"
}

This endpoint exposes the component execution result(error) and is the final resource to call in the component execution flow in the API.

HTTP Request

GET https://api.elastic.io/v1/exec/result/{EXECUTION_ID}

Parameter Required Description
EXECUTION_ID yes The id of a previously scheduled execution

Returns

Status Code Body Header Description
500 {message: 'Internal Server Error'} - An error occurred on the server
404 {message: 'Result does not exist.'} - An attempt to poll for a non scheduled execution was made
400 {message: 'Rejected.', reason: {...}} - The execution has resulted in an error. The body of the response will contain the error object under the 'reason’ property of the response.
200 { data: {...} } - The json representation of the execution result can be found under the 'data’ property of the response.

SSH keys

Retrieve all keys

Example Request:

curl https://api.elastic.io/v1/sshkey/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.sshkeys.list()
    .then(function(keys) {
        // do something with the keys
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "54982ee6bdf2a2030000000f",
    "title": "My Key",
    "fingerprint": "fingerprint",
    "user_id": "user_id",
    "key":"ssh_key"
  }
]

This endpoint retrieves list of user’s keys

HTTP Request

GET https://api.elastic.io/v1/sshkey/

Returns

Returns a ssh key’s metadata object if the call succeeded. The returned object will have an keys’s title, id and fingerPrint metadata.

Add new key

Example Request:

 curl https://api.elastic.io/v1/sshkey/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
       "key": "ssh-rsa YOUR KEY GOES HERE,
       "title": "My Key"
   }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.sshkeys.create({
    "key": "ssh-rsa YOUR KEY GOES HERE",
    "title": "My Key"
}).then(function(key) {
    // do something with the key
});

Example Response:

HTTP/1.1 201 OK
Content-Type: application/json

{
  "id": "54982ee6bdf2a2030000000f",
  "title": "My Key",
  "fingerprint": "fingerprint",
  "user_id": "user_id",
  "key":"ssh_key"
}

This endpoint adds new key to list of user’s keys

HTTP Request

POST https://api.elastic.io/v1/sshkey/

Arguments

Parameter Required Description
key yes valid RSA or DSA SSH public key
title no key title

Returns

Returns a ssh key’s metadata object if the call succeeded. The returned object will have an keys’s title, id and fingerPrint metadata.

Delete a key

Example Request:

curl https://api.elastic.io/v1/sshkey/{KEY_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -X DELETE
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.sshkeys.delete({KEY_ID});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{}

This endpoint delete specified ssh key

HTTP Request

DELETE https://api.elastic.io/v1/sshkey/{ID}

Arguments

Parameter Required Description
KEY_ID yes Key ID

Returns

Returns empty response on success request

Tasks

Create task

Example Request:

 curl https://api.elastic.io/v1/tasks \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
        "name" : "WebHook to Mailchimp",
        "nodes" : [
            {
                "function" : "elasticio/webhook:receive",
                "config": {
                    "payload": "email,first,last"
                }
            },
            {
                "function" : "elasticio/mapper:map",
                "config": {
                    "mapper" : {
                        "lastName" : "{{last}}",
                        "firstName" : "{{first}}",
                        "salutation" : "{{salutation}}",
                        "email_type" : "html",
                        "email" : "{{email}}"
                    },
                    "lookup_tables": {
                        "salutation": "lookup-table-id-to-be-used-for-salutation"
                    }
               }
            },
            {
                "function" : "elsaticio/mailchimp:subscribe",
                "account" : "54536902230d250700000016",
                "config": {
                    "listId" : "8779dd762e"
               }
            }
        ]
    }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.tasks.create({
    "name" : "WebHook to Mailchimp",
    "nodes" : [
        {
            "function" : "elasticio/webhook:receive@1234abc",
            "config": {
                "payload": "email,first,last"
            }
        },
        {
            "function" : "elasticio/mapper:map",
            "config": {
                "mapper" : {
                    "lastName" : "{{last}}",
                    "firstName" : "{{first}}",
                    "salutation" : "{{salutation}}",
                    "email_type" : "html",
                    "email" : "{{email}}"
                },
                "lookup_tables": {
                    "salutation": "lookup-table-id-to-be-used-for-salutation"
                }
           }
        },
        {
            "function" : "elsaticio/mailchimp:subscribe",
            "account" : "54536902230d250700000016",
            "config": {
                "listId" : "8779dd762e"
           }
        }
    ]
})
.then(function(task) {
    // do something with the task
});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id":"55083c567aea6f030000001a"
}

This endpoint creates a new task for user

HTTP Request

POST https://api.elastic.io/v1/tasks/

Parameter Required Description
name yes task name
nodes yes task nodes
cron no cron expression defining task’s scheduling period

Nodes format

{
    "function" : "{TEAM}/{COMPONENT}:{ACTION}@{REVISION}",
    "config": {
        "{KEY}": "{VALUE}",
        ...
    }
}

function key represents component to run. {TEAM} is name of team which owns component, {COMPONENT} is name of teams’s repository with component code, {ACTION} is action/trigger name to run and {REVISION} is git hash of commit in repository. If @{REVISION} is ommited - latest successfull build for {TEAM}/{COMPONENT} is used.

config key represents data which will be passed as config argument to action/trigger.

Returns

Returns tasks id object if the call succeeded.

Start a Task

Example Request:

curl -X POST https://api.elastic.io/v1/tasks/start/{TASK_ID} \
   -u {EMAIL}:{APIKEY}
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.tasks.start({TASK_ID});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "5538bd9646208d02b3000005",
  "status":"active"
}

This endpoint starts a given integration task.

HTTP Request

POST https://api.elastic.io/v1/tasks/start/{TASK_ID}

URL Parameters

Parameter Description
TASK_ID The ID of the task to start

Returns

Result of starting the task.

Stop a Task

Example Request:

curl -X POST https://api.elastic.io/v1/tasks/stop/{TASK_ID} \
   -u {EMAIL}:{APIKEY}
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.tasks.stop({TASK_ID});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "5538bd9646208d02b3000005",
  "status":"inactive"
}

This endpoint stops a given integration task.

HTTP Request

POST https://api.elastic.io/v1/tasks/stop/{TASK_ID}

URL Parameters

Parameter Description
TASK_ID The ID of the task to stop

Returns

Result of stopping the task.

Delete a Task

Example Request:

curl -X DELETE https://api.elastic.io/v1/tasks/{TASK_ID} \
   -u {EMAIL}:{APIKEY}
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.tasks.delete({TASK_ID});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "5538bd9646208d02b3000005",
  "status":"deleted"
}

This endpoint deleted a given integration task.

HTTP Request

DELETE https://api.elastic.io/v1/tasks/{TASK_ID}

URL Parameters

Parameter Description
TASK_ID The ID of the task to delete

Returns

Result of task deletion: task id and its new status (“deleted”)

Teams

Get user’s teams

Example Request:

curl https://api.elastic.io/v1/teams/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.teams.list()
    .then(function(teams) {
        // do something with the teams
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id":"55083c567aea6f030000001a",
        "name":"My team",
        "members":[
            "5508411b34e5ac0300000019",
            "510fc14d173cff0200000003"
        ]
    }
]

This endpoint retrieves list of user’s teams

HTTP Request

GET https://api.elastic.io/v1/teams/

Returns

Returns teams metadata object if the call succeeded.

Create team

Example Request:

 curl https://api.elastic.io/v1/teams \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
       "name": "My team"
   }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.teams.create({
    "name": "My team"
}).then(function(team) {
    // do something with the team
});

Example Response:

HTTP/1.1 201 OK
Content-Type: application/json

{
    "id":"55083c567aea6f030000001a",
    "name":"My team",
    "members":["5508411b34e5ac0300000019"]
}

This endpoint creates new team for user

HTTP Request

POST https://api.elastic.io/v1/teams/

Parameter Required Description
name no team name

Returns

Returns teams metadata object if the call succeeded.

Users

Retrieve your user

Example Request:

curl https://api.elastic.io/v1/users \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.users.me()
    .then(function(user) {
        // do something with your user
    });

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "54f4be3fe7d5224f91000001",
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@example.com"
}

This endpoint returns your own user.

HTTP Request

GET https://api.elastic.io/v1/users

Returns

Returns a user object if the call succeeded.

Create a user

Example Request:

curl https://api.elastic.io/v1/users \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
      "first_name": "John",
      "last_name": "Doe",
      "email": "test@example.com",
      "password": "secret",
      "company": "Doe & Partners"
   }'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.users.create({
    "first_name": "John",
    "last_name": "Doe",
    "email": "test@example.com",
    "password": "secret",
    "company": "Doe & Partners"
}).then(function(user) {
    // do something with the user
});

Example Response:

HTTP/1.1 201 OK
Content-Type: application/json

{
  "id": "54f4be3fe7d5224f91000001",
  "first_name": "John",
  "last_name": "Doe",
  "email": "test@example.com",
  "company": "Doe & Partners",
  "api_secret":"7a00b1ec-a0a8-4cea-84d2-d26052c8b788"
}

This endpoint registers a new user.

HTTP Request

POST https://api.elastic.io/v1/users

Arguments

Parameter Required Description
first_name yes The user’s first name
last_name yes The user’s last name
email yes The user’s email
password yes The user’s password
company no The user’s company
callback no Callback Url to call the result with

Returns

No Callback Provided

A created user object.

New user objects will be provided with an id and api_secret fields - these values cannot be created or edited by clients.

The api_secret field is used to communicate with the API on user’s behalf.

With Callback Provided

{"message": "accepted"}

When the user is created the provided callback_url will be called with the resulting user object.

New user objects will be provided with an id and api_secret fields - these values cannot be created or edited by clients.

The api_secret field is used to communicate with the API on user’s behalf.

Delete one of the created users

This method works with following limitations:

Example Request:

curl https://api.elastic.io/v1/users/{USER_ID} \
   -X DELETE \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
var client = require('elasticio-rest-node')(
    'YOUR_EMAIL', 'YOUR_API_KEY'
);

client.users.delete({USER_ID});

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message" : "Successfully delete user id=123456789"
}

HTTP Request

DELETE https://api.elastic.io/v1/users/123456

Returns

Returns an HTTP 200 in case of successful deletion

Errors

The elastic.io API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! Slown down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.