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'
);

Scheduled Executions

Preamble

In order to set up usage of some component in a certain node in certain Flow, some available configuration options could not be described in advance, because they depend on the context in each case.

Let’s consider an example when we have a component with a module, which allows retrieving a list of goods from some e-commerce platform. In this case, we have few configuration parameters, which should be configured in order to use a component in some flow, but all available options are different for different e-commerce installations.

The first such “dynamic” parameter is a category of a good. Each installation has its own set of goods categories.

Goods in different categories have different attributes set, so the structure of data in messages (metadata), produced by the module is dependent on selected category. So metadata also should be retrieved for each case.

And finally, each client uses own credential in order to connect connector with the e-commerce platform installation. Credential parameters have to be verified somehow before usage (at least in order to avoid confusing bugs while using component).

In order to solve each of three problems above, there are so-called scheduled executions, which allow running special methods of a component.

These methods are:

Each of the methods is executed in the same environment as a module of a component while executing of flows.

Scheduled execution workflow

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 method execution is scheduled by sending a request corresponding endpoint (see below). The API responds with 202 Accepted. The resource in the Location HTTP header is the URL to poll for execution results.
  2. The execution result is 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 of the execution.
  4. The results are retrieved from exec/result/{EXECUTION_ID}.

TODO – update and paste time sequence diagram.

Schedule a verifyCredentials

Example Request:

 curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_HASH}/verify-credential \
 -u {EMAIL}:{APIKEY} \ 
 -X POST -H 'Content-Type: application/json' -d '
 {
     "data": {
         "type": "verify-credential",
         "attributes": {
             "module": "getHello",
             "fields": {
                 "name" : "Kapish"
             }
         }
     }
TBD

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: 'https://api.elastic.io/v2/exec/poll/58becb8259a65f18c5c60eb0'

{
    "data": {
        "type": "execution-result",
        "id": "58becb8259a65f18c5c60eb0",
        "attributes": {
            "result": {},
            "status": "Pending request, waiting other process"
        }
    }
}

The endpoint allows to schedule an execution of verifyCredentials.

HTTP Request

GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_HASH}/verify-credential

Authorization

Component should be available for the client more about components access/sharing.

URL Parameters

Parameter Description
COMPONENT_ID The ID of the component
GIT_HASH Revision of the component’s build. Also there is “keyword” latest which means the most recent successful build.

Attributes

Parameter Required Description
module yes Name of a module of the component.
keys yes An object which represents the configuration of credential. Semantic is the same as attribute keys of Credential see more.

Schedule a getMetaModel

Example Request:

 curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_HASH}/dynamic-metadata \
 -u {EMAIL}:{APIKEY} \ 
 -X POST -H 'Content-Type: application/json' -d '
 {
    "data": {
        "type": "dynamic-metadata",
        "attributes": {
            "module": "{MODULE}",
            "fields": {
                "some_field" : "value",
                "another_field" : "another_value"
            }
        },
        "relationships": {
            "credential": {
                "type": "credential",
                "id": "{CREDENTIAL_ID}"
            }
        }
    }
TBD

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: 'https://api.elastic.io/v2/exec/poll/58becb8359a65f18c5c60ec4'

{
    "data": {
        "type": "execution-result",
        "id": "58becb8359a65f18c5c60ec4",
        "attributes": {
            "result": {},
            "status": "Pending request, waiting other process"
        }
    }
}

The endpoint allows to schedule an execution of getMetaModel.

HTTP Request

GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_HASH}/dynamic-metadata

Authorization

Component should be available for the client more about components access/sharing. Specified Credential (if any) should be available for the client.

URL Parameters

Parameter Description
COMPONENT_ID The ID of the component
GIT_HASH Revision of the component’s build. Also there is “keyword” latest which means the most recent successful build.

Attributes in request payload

Parameter Required Description
module yes Name of a module of the component.
fields yes An object which represents configuration. Semantic is the same when the module would be used for a node in a Flow see more.

Relationships in request payload

Parameter Required Description
credential depends on component If the credential is specified in the component descriptor for the module, credential should be created before and specified here.

Schedule a selectModel

Example Request:

 curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_HASH}/select-model\
 -u {EMAIL}:{APIKEY} \ 
 -X POST -H 'Content-Type: application/json' -d '
 {
    "data": {
        "type": "dynamic-metadata",
        "attributes": {
            "module": "{MODULE}",
            "fields": {
                "some_field" : "value",
                "another_field" : "another_value"
            }
        },
        "relationships": {
            "credential": {
                "type": "credential",
                "id": "{CREDENTIAL_ID}"
            }
        }
    }
TBD

Example Response:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: 'https://api.elastic.io/v2/exec/poll/58becb8059a65f18c5c60e41'

{
    "data": {
        "type": "execution-result",
        "id": "58becb8059a65f18c5c60e41",
        "attributes": {
            "result": {},
            "status": "Pending request, waiting other process"
        }
    }
}

The endpoint allows to schedule an execution of selectModel.

HTTP Request

GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_HASH}/select-model

Authorization

Component should be available for the client more about components access/sharing. Specified Credential (if any) should be available for the client.

URL Parameters

Parameter Description
COMPONENT_ID The ID of the component
GIT_HASH Revision of the component’s build. Also there is “keyword” latest which means the most recent successful build.

Attributes in request payload

Parameter Required Description
module yes Name of a module of the component.
fields yes An object which represents configuration. Semantic is the same when the module would be used for a node in a Flow see more.

Relationships in request payload

Parameter Required Description
credential depends on component If the credential is specified in the component descriptor for the module, credential should be created before and specified here.

Poll execution result status

Example Request:

curl https://api.elastic.io/v2/exec/result/{EXECUTION_ID} -u {EMAIL}:{APIKEY}
TBD

Response “In progress”:

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

{
    "data": {
        "type": "execution-result",
        "id": "58becb8059a65f18c5c60e41",
        "attributes": {
            "result": {
                "some_field_of_result": "value",   
                "another_field": "another_value"   
            }
        }
    }
}

Response “Result ready”:

HTTP/1.1 303 See Other
Content-Type: application/json
Location: 'https://api.elastic.io/v2/exec/result/58becb8059a65f18c5c60e41'

{
    "data": {
        "type": "execution-result",
        "id": "58becb8059a65f18c5c60e41",
        "attributes": {
            "result": {
                "some_field_of_result": "value",   
                "another_field": "another_value"   
            }
        }
    }
}

This endpoint allows polling a result of the execution. Once the execution is done, the endpoint responds with HTTP status code 303 and provides a resource for querying the result in the ‘Location’ header.

HTTP Request

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

URL Parameters

Parameter Description
EXECUTION_ID The ID of the execution

Returns

Status Code Header Description
200 - The execution hasn’t completed yet
303 Location The execution is finished and the result is ready. Resource to get the result is found in the 'Location header’
500 - Internal server error
404 - The execution does not exist (e.g. an attempt to poll for a non scheduled execution was made)

Get execution result

Example Request:

curl https://api.elastic.io/v2/exec/result/{EXECUTION_ID} -u {EMAIL}:{APIKEY}
TBD

Response

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

{
    "data": {
        "type": "execution-result",
        "id": "58becb8059a65f18c5c60e41",
        "attributes": {
            "result": {
                "some_field_of_result": "value",   
                "another_field": "another_value"   
            }
        }
    }
}

HTTP Request

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

URL Parameters

Parameter Description
EXECUTION_ID The ID of the execution

Returns

This endpoint returns a result of the execution. When execution is in progress and result is not ready yet, HTTP status code 409 is returned.

Credentials

Get all credentials available for the user

Example Request:

curl https://api.elastic.io/v2/credentials/?filter[component]={COMPONENT_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
// TBD

Example Response:

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

{
    "meta": {},
    "data": [
        {
            "id": "585430d3f02852a8a9fac45e",
            "type": "credential",
            "attributes": {
                "name": "CMS primary",
                "keys": {
                    "oauth": {
                        "key": "secret1"
                    }
                }
            },
            "relationships": {
                "user": {
                    "data": {
                        "id": "585430d3f02852a8a9fac45d",
                        "type": "user"
                    },
                    "links": {
                        "self": "/v2/users/585430d3f02852a8a9fac45d"
                    }
                },
                "component": {
                    "data": {
                        "id": "585430d2f02852a8a9fac456",
                        "type": "component"
                    },
                    "links": {
                        "self": "/v2/components/585430d2f02852a8a9fac456"
                    }
                }
            }
        },
        {
            "id": "585430d3f02852a8a9fac45f",
            "type": "credential",
            "attributes": {
                "name": "Refined CRM Manager login",
                "keys": {
                    "oauth": {
                        "key": "secret2"
                    },
                    "allowOption": "enabled"
                }
            },
             "relationships": {
                 "user": {
                     "data": {
                         "id": "585430d3f02852a8a9fac45d",
                         "type": "user"
                     },
                     "links": {
                         "self": "/v2/users/585430d3f02852a8a9fac45d"
                     }
                 },
                 "component": {
                     "data": {
                         "id": "585430d2f02852a8a9fac457",
                         "type": "component"
                     },
                     "links": {
                         "self": "/v2/components/585430d2f02852a8a9fac457"
                     }
                 }
             }
        }
    ]
}

This endpoint retrieves a list of credentials available for the user

HTTP Request

GET https://api.elastic.io/v2/credentials/

URL Query Parameters

Parameter Required Description
filter[component] no Only credentials belong to the given component id

Returns

Returns a list of credentials if the call succeeded.

Get a credential

Example Request:

curl https://api.elastic.io/v2/credentials/{CREDENTIAL_ID}/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
//TBD

Example Response:

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

{
    "meta": {},
    "data": {
        "id": "585430d3f02852a8a9fac45e",
        "type": "credential",
        "attributes": {
            "name": "CMS primary",
            "keys": {
                "oauth": {
                    "key": "secret1"
                }
            }
        },
        "relationships": {
            "user": {
                "data": {
                    "id": "585430d3f02852a8a9fac45d",
                    "type": "user"
                },
                "links": {
                    "self": "/v2/users/585430d3f02852a8a9fac45d"
                }
            },
            "component": {
                "data": {
                    "id": "585430d2f02852a8a9fac456",
                    "type": "component"
                },
                "links": {
                    "self": "/v2/components/585430d2f02852a8a9fac456"
                }
            }
        }        
    }
}

This endpoint retrieves one of a credential available for the user

HTTP Request

GET https://api.elastic.io/v2/credentials/{CREDENTIAL_ID}/

URL Parameters

Parameter Description
CREDENTIAL_ID The ID of the credential

Returns

Returns a credential object if the call succeeded.

Add a new credential

Example Request:

curl https://api.elastic.io/v2/credentials/ \
    -u {EMAIL}:{APIKEY} \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' -d '
    {
        "data": {
            "type": "credential",
            "attributes": {
                "name": "Spreadsheet",
                    "keys": {
                        "oauth": {
                            "key": "secret1"
                        }
                }
            },
            "relationships": {
                "component": {
                    "data": {
                        "id": "585430d2f02852a8a9fac456",
                        "type": "component"
                    }
                }
            }
        }
    }'
//TBD

Example Response:

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

{
   "data": {
       "id": "585430d3f02852a8a9fac45e",
       "type": "credential",
       "attributes": {
           "name": "CMS primary",
           "keys": {
               "oauth": {
                   "key": "secret1"
               }
           }
       },
        "relationships": {
            "user": {
                "data": {
                    "id": "585430d3f02852a8a9fac45d",
                    "type": "user"
                },
                "links": {
                    "self": "/v2/users/585430d3f02852a8a9fac45d"
                }
            },
            "component": {
                "data": {
                    "id": "585430d2f02852a8a9fac456",
                    "type": "component"
                },
                "links": {
                    "self": "/v2/components/585430d2f02852a8a9fac456"
                }
            }
        }         
   }
}

This endpoint allows to create a new credential

HTTP Request

POST https://api.elastic.io/v2/credentials/

Arguments

Parameter Required Description
type yes A value should be “credential”
attributes.name no Credential name. An automatic name will be generated if the parameter is omitted
relationships.component.data.id yes The component id this credential is for
relationships.component.data.type yes A value should be “component”
attributes.keys no An object which represents component’s configuration (OAuth keys, etc.)

Returns

Returns credential object if the call succeeded.

Modify a credential

Example Request:

curl https://api.elastic.io/v2/credentials/{CREDENTIAL_ID}/ \
   -u {EMAIL}:{APIKEY} \
   -X PATCH \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
        "data": {
            "id": "585430d3f02852a8a9fac45e",
            "type": "credential",
            "attributes": {
                "keys": {
                    "key1": "updated value"  
                }
            }             
        }
    }'
//TBD

Example Response:

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

{
   "data": {
       "id": "585430d3f02852a8a9fac45e",
       "type": "credential",
       "attributes": {
           "name": "CMS primary",
           "keys": {
                "key1": "updated value"
           }
       },
        "relationships": {
            "component": {
                "data": {
                    "id": "585430d2f02852a8a9facaaa",
                    "type": "component"
                },
                "links": {
                    "self": "/v2/component/585430d2f02852a8a9facaaa"
                }                
            },
            "user": {
                "data": {
                    "id": "585430d3f02852a8a9fac45d",
                    "type": "user"
                },
                "links": {
                    "self": "/v2/users/585430d3f02852a8a9fac45d"
                }
            }
        }              
   }
}

This endpoint modifies credential

HTTP Request

PATCH https://api.elastic.io/v2/credentials/{CREDENTIAL_ID}/

URL Parameters

Parameter Description
CREDENTIAL_ID The ID of the credential

Arguments

Parameter Required Description
id yes A value should be the same as URL parameter CREDENTIAL_ID
type yes A value should be “credential”
attributes.name no Credential name. Will remain untouched if value omitted.
attributes.keys no An object which represents component’s configuration. Will remain untouched if value omitted. Please note, that “keys” object is overwritten entirely.

Returns

Returns a modified credential object if the call succeeded.

Flows

Retrieve all flows

Example Request:

 curl https://api.elastic.io/v2/flows?page[size]=20&page[number]=1 \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json'
TBD

Example Response:

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

{
    "data": [
        {
            "type": "flow",
            "id": "585918da586224001b96de89",
            "attributes": {
              "name": "Timer to E-Mail Test",
              "status": "inactive",
              "type": "ordinary",
              "graph": {
                "nodes": [
                  {
                    "id": "step_1",
                    "command": "elasticio/timer:timer",
                    "fields": {
                      "interval": "minute"
                    }
                  },
                  {
                    "id": "step_2",
                    "command": "elasticio/email:send"
                  }
                ],
                "edges": [
                  {
                    "source": "step_1",
                    "target": "step_2",
                    "config": {
                      "mapper": {
                        "to": "info@acme.org",
                        "subject": "Test",
                        "textBody": "{{fireTime}}"
                      }
                    }
                  }
                ]
              }
            },
            "relationships": {
              "user": {
                "data": {
                  "type": "user",
                  "id": "560e5a27734d480a00000002"
                },
                "links": {
                  "self": "/v2/users/560e5a27734d480a00000002"
                }
              },
              "organization": {
                "data": {
                  "type": "organization",
                  "id": "573dd76962436c349f000003"
                },
                "links": {
                  "self": "/v2/organizations/573dd76962436c349f000003"
                }
              }
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }

}

This endpoint retrieves all flows for user or organization

HTTP Request

GET https://api.elastic.io/v2/flows/

URL Query Parameters

Parameter Required Description Default
page[size] No Amount of items per page 50
page[number] No Number of page 1

Returns

Returns all flows belonging to user or organization.

Retrieve a flow by ID

Example Request:

curl https://api.elastic.io/v2/flows/{FLOW_ID} \
   -u {EMAIL}:{APIKEY}
TDB

Example Response:

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

{
  "data": {
    "type": "flow",
    "id": "585918da586224001b96de89",
    "attributes": {
      "name": "Timer to E-Mail Test",
      "status": "inactive",
      "type": "ordinary",
      "graph": {
        "nodes": [
          {
            "id": "step_1",
            "command": "elasticio/timer:timer",
            "fields": {
              "interval": "minute"
            }
          },
          {
            "id": "step_2",
            "command": "elasticio/email:send"
          }
        ],
        "edges": [
          {
            "source": "step_1",
            "target": "step_2",
            "config": {
              "mapper": {
                "to": "info@acme.org",
                "subject": "Test",
                "textBody": "{{fireTime}}"
              }
            }
          }
        ]
      }
    },
    "relationships": {
      "user": {
        "data": {
          "type": "user",
          "id": "560e5a27734d480a00000002"
        },
        "links": {
          "self": "/v2/users/560e5a27734d480a00000002"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "573dd76962436c349f000003"
        },
        "links": {
          "self": "/v2/organizations/573dd76962436c349f000003"
        }
      }
    }
  },
  "meta": {}
}

This endpoint returns a flow for given ID

HTTP Request

GET https://api.elastic.io/v2/flows/{FLOW_ID}

URL Parameters

Parameter Description
FLOW_ID The ID of the flow to retrieve

Returns

The flow with given ID

Create a flow

Example Request:

 curl https://api.elastic.io/v2/flows \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
      "data": {
        "type": "flow",
        "attributes": {
          "name": "Timer to E-Mail",
          "status": "inactive",
          "type": "ordinary",
          "graph": {
            "nodes": [
              {
                "id": "step_1",
                "command": "elasticio/timer:timer",
                "fields": {
                  "interval": "minute"
                }
              },
              {
                "id": "step_2",
                "command": "elasticio/email:send"
              }
            ],
            "edges": [
              {
                "source": "step_1",
                "target": "step_2",
                "config": {
                  "mapper": {
                    "to": "info@acme.org,
                    "subject": "Test",
                    "textBody": "{{fireTime}}"
                  }
                }
              }
            ]
          }
        }
      }
    }'
TBD

Example Response:

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

{
  "data": {
    "type": "flow",
    "id": "585918da586224001b96de89",
    "attributes": {
      "name": "Timer to E-Mail Test",
      "status": "inactive",
      "type": "ordinary",
      "graph": {
        "nodes": [
          {
            "id": "step_1",
            "command": "elasticio/timer:timer",
            "fields": {
              "interval": "minute"
            }
          },
          {
            "id": "step_2",
            "command": "elasticio/email:send"
          }
        ],
        "edges": [
          {
            "source": "step_1",
            "target": "step_2",
            "config": {
              "mapper": {
                "to": "info@acme.org",
                "subject": "Test",
                "textBody": "{{fireTime}}"
              }
            }
          }
        ]
      }
    },
    "relationships": {
      "user": {
        "data": {
          "type": "user",
          "id": "560e5a27734d480a00000002"
        },
        "links": {
          "self": "/v2/users/560e5a27734d480a00000002"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "573dd76962436c349f000003"
        },
        "links": {
          "self": "/v2/organizations/573dd76962436c349f000003"
        }
      }
    }
  },
  "meta": {}
}

This endpoint creates a flow for current user or his organization

HTTP Request

POST https://api.elastic.io/v2/flows/

Arguments

Parameter Required Description
type yes A value should be “flow”
attributes.name yes Flow name
attributes.status yes Flow status. May be any of: active, inactive
attributes.type yes Flow type. May be any of: ordinary, long_running
attributes.graph yes Flow graph representing component connections

Returns

Returns the created flow

Lookup tables

Get lookup tables

Lists available lookup tables

Example Request:

 curl https://api.elastic.io/v2/lookups \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'

Example Response:


{
    "data": [{
        "type": "lookup",
        "id": "5863f65ecc753f2441c88e68",
        "attributes": {
            "title": "lookup title",
            "data": {
              "key": "value"
            }
        },
        "relationships": {
            "user": {
                "data": {
                    "type": "user",
                    "id": "585d389b90ea62ce348a478b"
                },
                "links": {
                    "self": "/v2/users/585d389b90ea62ce348a478b"
                }
            },
            "organization": {
                "data": {
                    "type": "organization",
                    "id": "58400dc7c9ab5757f8ef1f81"
                },
                "links": {
                    "self": "/v2/organizations/58400dc7c9ab5757f8ef1f81"
                }
            }
        }
    }],
    "meta": {}
}

Create lookup table

Example Request:

 curl https://api.elastic.io/v2/lookups \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
      "data": {
          "type": "lookup",
          "attributes": {
              "title": "lookup example",
              "data": {
                  "key": "value"
              }
          }
      }
   }'
 TBD

Example Response:

{
    "data": {
        "type": "lookup",
        "id": "5863f7136ef9da255ad9a9bc",
        "attributes": {
            "title": "mylookuptitle",
            "data": {
                "key": "value"
            }
        },
        "relationships": {
            "user": {
                "data": {
                    "type": "user",
                    "id": "585d389b90ea62ce348a478b"
                },
                "links": {
                    "self": "/v2/users/585d389b90ea62ce348a478b"
                }
            },
            "organization": {
                "data": {
                    "type": "organization",
                    "id": "58400dc7c9ab5757f8ef1f81"
                },
                "links": {
                    "self": "/v2/organizations/58400dc7c9ab5757f8ef1f81"
                }
            }
        }
    },
    "meta": {}
}
Parameter Required Description
title yes Lookup table name
data yes key/value

Update Lookup table

Parameter Required Description
title yes Lookup table name
data yes key/value

Example Request:

 curl https://api.elastic.io/v2/lookups/{LookupId} \
   -X PUT \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
      "data": {
          "type": "lookup",
          "id": "{LookupId}",
          "attributes": {
              "title": "new lookup title",
              "data": {
                  "key": "value"
              }
          }
      }
   }'
 TBD

Remove lookup table

Example Request:

 curl https://api.elastic.io/v2/organizations/{LookupId} \
    -X DELETE    \
    -u {EMAIL}:{APIKEY}'
 TBD

Example Response:

HTTP/1.1 204 No Content

Components

Component access and sharing

Each Component belongs to a Team. Each User who is a member of the team can edit the component. If a team is created in an Organization, it can be said that the component belongs to the organization transitively, so each member of the organization can edit the component.

The component has an attribute access, which indicates how is the component shared by the other clients. “Shared” means, that the component can be used by the users in their flows. There are three sharing modes:

Accordingly, a set of components, available for each user is consist of: not shared components from the user’s team, components with tenant access and global components.

Retrieve components

Example Request:

curl https://api.elastic.io/v2/components \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": [
        {
            "type": "component",
            "id": "{COMPONENT_ID}",
            "attributes": {
                "name": "component name",
                "team_name": "{team_name}"
            },
            "relationships": {
                "versions": {
                    "links": {
                        "related": "/v2/components/{COMPONENT_ID}/versions"
                    }
                },
                "latest_version": {
                    "links": {
                        "self": "/v2/components/{COMPONENT_ID}/versions/latest"
                    },
                    "data": {
                        "type": "version",
                        "id": "{GIT_REVISION}"
                    }
                }
            },
            "included": [
                {
                    "type": "version",
                    "id": "{GIT_REVISION}",
                    "attributes": {
                        "date": 1487846132213,
                        "versionNumber": 1
                    },
                    "relationships": {
                        "descriptor": {
                            "links": {
                                "self": "/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
                            }
                        }
                    }
                },
                {
                    "id": "{GIT_REVISION}",
                    "type": "descriptor",
                    "attributes": {
                        "description": "desc",
                        "icon": "BASE64",
                        "is_latest": true,
                        "language": "nodejs",
                        "repo_name": "repo_name",
                        "sailor_version": "1.0.0",
                        "team_name": "team_name",
                        "title": "title",
                        "triggers": {
                            "select": "<Triggers Object>"
                        },
                        "actions": {
                            "update": "<Actions Object>"
                        }
                    }
                }
            ]
        }
    ],
    "meta": {}
}

This endpoint retrieves a list of available components. Response includes latest descriptor for each component. More details about the component descriptors can be found here.

HTTP Request

GET https://api.elastic.io/v2/components

URL Query Parameters

Parameter Required Description
filter[access] no Allowed values: private (only components from own teams returned), public (only shared components from the other teams) and all (default value, returns all abailable components).

Returns

Returns repositories metadata object if the call succeeded.

Response fields

Field Type Description
icon String Icon (base64 encoded)
triggers Object <Triggers Object>
actions Object <Actions Object>

Retrieve a single component

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": 
        {
            "type": "component",
            "id": "{COMPONENT_ID}",
            "attributes": {
                "name": "component name",
                "team_name": "{team_name}"
            },
            "relationships": {
                "versions": {
                    "links": {
                        "related": "/v2/components/{COMPONENT_ID}/versions"
                    }
                },
                "latest_version": {
                    "links": {
                        "self": "/v2/components/{COMPONENT_ID}/versions/latest"
                    },
                    "data": {
                        "type": "version",
                        "id": "{GIT_REVISION}"
                    }
                }
            },
            "included": [
                {
                    "type": "version",
                    "id": "{GIT_REVISION}",
                    "attributes": {
                        "date": 1487846132213,
                        "versionNumber": 1
                    },
                    "relationships": {
                        "descriptor": {
                            "links": {
                                "self": "/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
                            }
                        }
                    }
                },
                {
                    "id": "{GIT_REVISION}",
                    "type": "descriptor",
                    "attributes": {
                        "description": "desc",
                        "icon": "BASE64",
                        "is_latest": true,
                        "language": "nodejs",
                        "repo_name": "repo_name",
                        "sailor_version": "1.0.0",
                        "team_name": "team_name",
                        "title": "title",
                        "triggers": {
                            "select": "<Triggers Object>"
                        },
                        "actions": {
                            "update": "<Actions Object>"
                        }
                    }
                }
            ]
        },
        "meta": {}
    }

HTTP Request

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

Authorization

The component should be accessible to the client (e.g. component from the own team or shared one) unless it has TenantAdmin role. Contact support team to get this role.

Returns

This endpoint returns a component object and includes latest descriptor for each component.

Response fields

Field Type Description
icon String Icon (base64 encoded)
triggers Object <Triggers Object>
actions Object <Actions Object>

Retrieve component versions

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": [
        {
            "type": "version",
            "id": "{GIT_REVISION}",
            "relationships": {
                "descriptor": {
                    "links": {
                        "self": "/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
                    }
                }
            }
        },
        {
            "type": "version",
            "id": "{GIT_REVISION}",
            "attributes": {
                "date": 1487846132213,
                "versionNumber": 1
            },
            "relationships": {
                 "component": {
                    "data": {
                        "id": {COMPONENT_ID},
                        "type": 'component'
                    },
                    "links": {
                        "self": "/v2/components/{COMPONENT_ID}"
                    }
                },
                "descriptor": {
                    "data": {
                        "id": {GIT_REVISION},
                        "type": 'descriptor'
                    },
                    "links": {
                        "self": "/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
                    }
                }
            }
        }
    ],
    "meta": {}
}

This endpoint retrieves list of component’s versions

HTTP Request

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

Authorization

The component should be accessible to the client (e.g. component from the own team or shared one) unless it has TenantAdmin role. Contact support team to get this role.

Returns

Returns repositories build metadata object if the call succeeded.

Retrieve a single component descriptor

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "id": "{GIT_REVISION}",
        "type": "descriptor",
        "attributes": {
            "description": "desc",
            "icon": "BASE64",
            "is_latest": true,
            "language": "nodejs",
            "repo_name": "repo_name",
            "sailor_version": "1.0.0",
            "team_name": "team_name",
            "title": "title",
            "triggers": {
                "select": "<Triggers Object>"
            },
            "actions": {
                "update": "<Actions Object>"
            }
        }
    },
    "meta": {}
}

This endpoint retrieves an information about single component by it’s ID and/or version, for latest version type latest More details you can find here.

HTTP Request

GET https://api.elastic.io/v2/components/{COMPONENT_ID}/version/{GIT_REVISION}/descriptor

or

GET https://api.elastic.io/v2/components/{COMPONENT_ID}/version/latest/descriptor

URL Parameters

Parameter Description
COMPONENT_ID The ID of a user
GIT_REVISION Revision of the component’s build. Also there is “keyword” latest which means the most recent successful build.

Authorization

The component should be accessible for the client (e.g. component from own team or shared one) unless it has TenantAdmin role. Contact support team to get this role.

Returns

Returns component descriptor if the call succeeded.

Create component repository

Example Request:

curl https://api.elastic.io/v2/components/ \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
   -H 'Content-Type: application/json' -d '
   {
       "data": {
           "type": "component",
           "attributes": {
               "name": "mycomponent"
           },
           "relationships": {
               "team": {
                   "data": {
                       "type": "team",
                       "id": "{TEAM_ID}"
                   }
               }
           }
       }
   }'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "type": "component",
        "id": "58a410b58224d9b2f99a687b",
        "attributes": {
            "name": "mycomponent",
            "team_name": "my_hackers",
            "icon": "{BASE64_ICON}
        },
        "relationships": {
            "versions": {
                "links": {
                    "related": "/v2/components/58a410b58224d9b2f99a687b/versions"
                }
            }
        }
    },
    "meta": {}
}

This endpoint creates repository for component

Returns

Returns component’s metadata object if the call succeeded.

Update component access

Allows changing access from team to tenant mode.

Please note, that this action is irreversible i.e. API does not allow to change access back to team.

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID} \
   -X PATCH \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
   -H 'Content-Type: application/json' -d '
   {
       "data": {
           "type": "component",
           "attributes": {
               "access": "tenant"
           }
       }
   }'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "type": "component",
        "id": "58a410b58224d9b2f99a687b",
        "attributes": {
            "name": "mycomponent",
            "team_name": "my_hackers"
        },
        "relationships": {
            "versions": {
                "links": {
                    "related": "/v2/components/58a410b58224d9b2f99a687b/versions"
                }
            }
        }
    },
    "meta": {}
}

Authorization

This request is authorized for a user with TenantAdmin role only. Contact support team to get this role.

Returns

Returns updated component’s metadata object if the call succeeded.

Remove a component

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID} \
   -X DELETE \
   -u {EMAIL}:{APIKEY}
TBD

Example Response:

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

This endpoint removes component from the database. Component’s slugs will be removed later automatically (TBD).

HTTP Request

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

Authorization

The component should belong to one of the client’s team or organization respectively unless it has TenantAdmin role. Contact support team to get this role.

Returns

200 HTTP response code if the call succeeds, error otherwise.

Get component’s environment variables

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID}/env \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'

TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "attributes": {
            "vars": {
                "MY_ENV_VAR": "env_var_value"
            }
        },
        "id": "{REPO_ID}",
        "type": "component-env"
    },
    "meta": {}
}

This endpoint shows env vars for given component.

HTTP Request

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

Authorization

The component should be accessible to the client (e.g. component from the own team or shared one) unless it has TenantAdmin role. Contact support team to get this role.

Returns

Returns environment variables

Set component’s environment variables

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID}/env \
   -X PUT
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
   -H 'Content-Type: application/json' -d '
   {
       "data": {
           "type": "component-env",
           "attributes": {
               "vars": {
                   "MY_ENV_VAR": "env_var_value"
               }
           }
       }
   }'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "data": {
        "attributes": {
            "vars": {
                "MY_ENV_VAR": "env_var_value"
            }
        },
        "id": "{REPO_ID}",
        "type": "component-env"
    },
    "meta": {}
}

This endpoint replaces env vars for given component.

HTTP Request

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

Authorization

The component should belong to one of the client’s team or organization respectively unless it has TenantAdmin role. Contact support team to get this role.

Returns

Returns environment variables

Organizations

Create an organization

Example Request:

 curl https://api.elastic.io/v2/organizations \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
       {
           "data": {         
               "type": "organization",
               "attributes": {
                   "name": "My Org"
               }
           }
       }'
 TBD

Example Response:

{ 
  "data":
    { 
      "id": "58455777a0aec4f377faefc1",
      "type": "organization",
      "attributes": { 
        "name": "My Org"
      } 
   },
  "meta": {} 
}

This endpoint allows to create an organization.

HTTP Request

POST https://api.elastic.io/v2/organizations

Authorization

This request is authorized to only a user with TenantAdmin role. Contact support team to get this role.

Parameter Required Description
type yes A value should be “organization”
attributes.name yes Name of the organization

Returns

Returns Organization object if the call succeeded

Get organization

Example Request:

 curl https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}?include=members,invites \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
 TBD

Example Response:

{
    "meta": {},
    "data": {
        "id": "58400dc7c9ab5757f8ef1f81",
        "type": "organization",
        "attributes": {
            "name": "horns&hoofs"
        },
        "relationships": {
            "members": {
                "data": [
                    {
                        "type": "member",
                        "id": "588f832b87d7c27c7d5cc37b"
                    },
                    {
                        "type": "member",
                        "id": "588f832b87d7c27c7d5cc37a"
                    }
                ],
                "links": {
                    "self": "/v2/organizations/58400dc7c9ab5757f8ef1f81/members"
                }
            },
            "invites": {
                "data": [
                    {
                        "type": "organization-invite",
                        "id": "588f832b87d7c27c7d5cc37e"
                    },
                    {
                        "type": "organization-invite",
                        "id": "588f832b87d7c27c7d5cc37f"
                    }
                ],
                "links": {
                    "self": "/v2/organizations/58400dc7c9ab5757f8ef1f81/members/pending"
                }
            }
        }
    },
    "included": [
        {
            "type": "member",
            "id": "588f832b87d7c27c7d5cc37a",
            "attributes": {
                "first_name": "Santos",
                "last_name": "Mitchell",
                "email": "Katelynn_Fritsch@gmail.com",
                "role": "admin"
            }
        },
        {
            "type": "member",
            "id": "588f832b87d7c27c7d5cc37b",
            "attributes": {
                "first_name": "Kacie",
                "last_name": "Howe",
                "email": "Rusty_Goodwin@hotmail.com",
                "role": "integrator"
            }
        },
        {
            "type": "organization-invite",
            "id": "588f832b87d7c27c7d5cc37e",
            "attributes": {
                "email": "invited-1@example.org",
                "role": "guest"
            }
        },
        {
            "type": "organization-invite",
            "id": "588f832b87d7c27c7d5cc37f",
            "attributes": {
                "email": "invited-2@example.org",
                "role": "integrator"
            }
        }
    ]
}

This endpoints returns an Organization object for certain organization id.

HTTP Request

GET https://api.elastic.io/v2/organizations/ORGANIZATION_ID/

Authorization

Client has to be a member of the organization or to have TenantAdmin role (contact support team to get this role).

URL Parameters

Parameter Description
ORGANIZATION_ID The ID of the organization

URL Query Parameters

Parameter Required Description
include no Whether include or not full resource objects in response for related entities. Possible values: members and/or invites.

Get a list of members of Organization

Example Request:

 curl https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
 TBD

Example Response:

{
    "meta": {},
    "data": [
        {
            "type": "member",
            "id": "588f832b87d7c27c7d5cc37a",
            "attributes": {
                "first_name": "Santos",
                "last_name": "Mitchell",
                "email": "Katelynn_Fritsch@gmail.com",
                "role": "admin"
            }
        },
        {
            "type": "member",
            "id": "588f832b87d7c27c7d5cc37b",
            "attributes": {
                "first_name": "Kacie",
                "last_name": "Howe",
                "email": "Rusty_Goodwin@hotmail.com",
                "role": "integrator"
            }
        }
    ]
}

This endpoints returns a list of all members of certain Organization.

HTTP Request

GET https://api.elastic.io/v2/organizations/ORGANIZATION_ID/members/

Authorization

Client has to be a member of the organization.

URL Parameters

Parameter Description
ORGANIZATION_ID The ID of the organization

Get a list of pending members (invites) of Organization

Example Request:

 curl https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/invites/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
 TBD

Example Response:

{
    "meta": {},
    "data": [
        {
            "type": "organization-invite",
            "id": "588f832b87d7c27c7d5cc37e",
            "attributes": {
                "email": "invited-1@example.org",
                "role": "guest"
            }
        },
        {
            "type": "organization-invite",
            "id": "588f832b87d7c27c7d5cc37f",
            "attributes": {
                "email": "invited-2@example.org",
                "role": "integrator"
            }
        }
    ]
}

This endpoints returns a list of pending members (invites) for certain Organization.

HTTP Request

GET https://api.elastic.io/v2/organizations/ORGANIZATION_ID/invites/

Authorization

Client has to be a member of the organization.

URL Parameters

Parameter Description
ORGANIZATION_ID The ID of the organization

Invite a user to organization

Example Request:

curl https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/invites/ \
    -X POST \
    -u {EMAIL}:{APIKEY} \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' -d '
    {
       "data": {
           "type": "invite",
           "attributes": {
               "email": "user-to-invite@my-company.com",
               "role": "admin"
           }
       }
    }'
 TBD

Example Response:

{
   "data": {
       "type": "invite",
       "attributes": {
           "email": "user-to-invite@my-company.com",
           "role": "admin"
       }
   }
}

This endpoint allows to invite a user to organization.

HTTP Request

POST https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members/invite

Authorization

This request is authorized for organization members with role Admin.

URL Parameters

Parameter Description
ORGANIZATION_ID The ID of the organization

Payload Parameters

Parameter Required Description
type yes A value should be “invite”.
attributes.email yes Email.
attributes.role yes Available roles are: admin, integrator and guest.

Returns

Returns invite object if the call succeeded

Add a new member to organization

Example Request:

curl https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members/ \
    -X POST \
    -u {EMAIL}:{APIKEY} \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' -d '
    {
       "data": {
           "type": "member",
           "id": "{USER_ID}",
           "attributes": {
               "role": "{ROLE}"
           }
       }
    }'
 TBD

Example Response:

{
   "data": {
        "type": "member",
        "id": "588f832b87d7c27c7d5cc37a",
        "attributes": {
            "first_name": "Santos",
            "last_name": "Mitchell",
            "email": "Santos_Mitchell@example.com",
            "role": "admin"
        }
   }
}

This endpoint allows adding a user to a certain organization as a member. No invitation email will be sent. The user becomes a member immediately.

HTTP Request

POST https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members

Authorization

This request is authorized for a user with TenantAdmin role only. Contact support team to get this role.

Payload Parameters

Parameter Required Description
id yes id of an already registered user, who will be added as a member of the organization
type yes A value should be “member”.
attributes.role yes Available roles are: admin, integrator and guest.

Returns

Returns member object if the call succeeded

Update membership in Organization

Example Request:

curl https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members/{USER_ID}/ \
    -X PATCH  \
    -u {EMAIL}:{APIKEY} \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' -d '
    {
       "data": {
           "type": "member",
           "id": "{USER_ID}",
           "attributes": {
               "role": "{NEW_ROLE}"
           }
       }
    }'
 TBD

Example Response:

{
   "data": {
        "type": "member",
        "id": "588f832b87d7c27c7d5cc37a",
        "attributes": {
            "first_name": "Santos",
            "last_name": "Mitchell",
            "email": "Santos_Mitchell@example.com",
            "role": "admin"
        }
   }
}

This endpoint allows updating a membership of a given user. Only role attribute can be updated. In order to update attributes of a User object (e.g. email), use /v2/users endpoints.

HTTP Request

PATCH https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members/{USER_ID}/

Authorization

This request is authorized for organization members with role Admin.

URL Parameters

Parameter Description
ORGANIZATION_ID The ID of the organization
USER_ID The ID of the user to be updated

Payload Parameters

Parameter Required Description
type yes A value should be “member”.
id yes id of an already registered user, must match URL param {USER_ID}
attributes.role yes Available roles are: admin, integrator and guest.

Returns

Returns member object if the call succeeded

Remove member from organization

Example Request:

 curl https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members/{USER_ID}/ \
    -X DELETE    \
    -u {EMAIL}:{APIKEY}'
 TBD

Example Response:

HTTP/1.1 200 OK

Remove a membership of the User in the Organization. Ownership of those user’s associated data will be transferred to admin User performing this operation: * flows * credentials * lookups * developers teams membership

HTTP Request

DELETE https://api.elastic.io/v2/organizations/{ORGANIZATION_ID}/members/{USER_ID}/

Authorization

This request is authorized for a user with TenantAdmin role only. Contact support team to get this role.

URL Parameters

Parameter Description
ORGANIZATION_ID The ID of the organization
USER_ID The ID of the user, which should leave the organization

Returns

Responds with 204 No content if the call succeeded (with empty body).

Users

Retrieve your user

Example Request:

curl https://api.elastic.io/v2/users/me \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
//TBD

Example Response:

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

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

This endpoint returns your own user.

HTTP Request

GET https://api.elastic.io/v2/users/me

Returns

Returns a user object if the call succeeded.

Get a certain user

Example Request:

curl https://api.elastic.io/v2/users/{USER_ID} \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
//TBD

Example Response:

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

{
    "data": {
        "id": "54f4be3fe7d5224f91000002",
        "type": "user",
        "attributes": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "test@example.com"
        }
    }
}

This endpoint returns requested user if the call succeeded.

HTTP Request

GET https://api.elastic.io/v2/users/{USER_ID}

URL Parameters

Parameter Description
USER_ID The ID of a user

Authorization

This request is authorized to only a user with TenantAdmin role (contact support to get this role).

Returns

Returns a user object if the call succeeded.

Get a list of users

Example Request (with paging):

curl https://api.elastic.io/v2/users/?page[size]=1&page[number]=5 \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'

Example Response (with paging):

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

{
    "meta": {
        "total": 6,
        "page": 5,
        "per_page": 1,
        "total_pages": 6
    },
    "data": [
        {
            "id": "588f8bd23abb797f8c293646",
            "type": "user",
            "attributes": {
                "first_name": "Robyn",
                "last_name": "Kerluke",
                "email": "robyn@outcast.org",
                "company": "Olson Group"
            }
        }
    ]
}

Example Request (default paging):

curl https://api.elastic.io/v2/users/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
//TBD

Example Response (default paging):

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

{
    "meta": {
        "total": 6,
        "page": 1,
        "per_page": 50,
        "total_pages": 1
    },
    "data": [
        {
            "id": "588f8b04b84a6a7f3e47668d",
            "type": "user",
            "attributes": {
                "first_name": "Joannie",
                "last_name": "Smitham",
                "email": "client@my.org",
                "company": "Ward - Wiegand"
            }
        },
        {
            "id": "588f8b04b84a6a7f3e47668e",
            "type": "user",
            "attributes": {
                "first_name": "Eulalia",
                "last_name": "Hyatt",
                "email": "user-2@my.org",
                "company": "Pfannerstill and Sons"
            }
        },
        {
            "id": "588f8b04b84a6a7f3e47668f",
            "type": "user",
            "attributes": {
                "first_name": "Bertram",
                "last_name": "Davis",
                "email": "user-1@aliens.org",
                "company": "Auer, Ebert and Ledner"
            }
        },
        {
            "id": "588f8b04b84a6a7f3e476690",
            "type": "user",
            "attributes": {
                "first_name": "Marianne",
                "last_name": "Sawayn",
                "email": "client@outcast.org",
                "company": "O'Kon, Abshire and Dooley"
            }
        },
        {
            "id": "588f8b04b84a6a7f3e476691",
            "type": "user",
            "attributes": {
                "first_name": "Esta",
                "last_name": "Abbott",
                "email": "another@outcast.org",
                "company": "Turcotte - Christiansen"
            }
        },
        {
            "id": "588f8b04b84a6a7f3e476692",
            "type": "user",
            "attributes": {
                "first_name": "Kayleigh",
                "last_name": "Howell",
                "email": "tenant-admin@example.com",
                "company": "Zemlak, Thiel and O'Kon"
            }
        }
    ]
}

This endpoint returns a list of users.

HTTP Request

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

URL Query Parameters

Parameter Required Description Default
page[size] No Amount of items per page 50
page[number] No Number of page 1

Authorization

This request is authorized for a user with TenantAdmin role only. Contact support team to get this role.

Returns

Returns a list of user objects if the call succeeded.

Create a user

Example Request:

curl https://api.elastic.io/v2/users \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
        "data": {
            "type": "user",
            "attributes": {
                "first_name": "John",
                "last_name": "Doe",
                "email": "test@example.com",
                "password": "secret",
                "company": "Doe & Partners"
            }
        }
    }'
//TBD

Example Response:

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

{
    "data": {
        "id": "54f4be3fe7d5224f91000001",
        "type": "user",
        "attributes": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "test@example.com",
            "company": "Doe & Partners"
        }
    }
}

This endpoint registers a new user. This request is authorized only for a user with TenantAdmin role. Contact support team to get this role.

HTTP Request

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

Arguments

Parameter Required Description
attributes.first_name yes The user’s first name
attributes.last_name yes The user’s last name
attributes.email yes The user’s email
attributes.password yes The user’s password. Must be at least 8 characters long.
attributes.company no The user’s company

Returns

New user objects will be provided with an id field - this value cannot be created or edited by clients.

Delete a user

Example Request:

curl https://api.elastic.io/v2/users/{USER_ID} \
   -X DELETE -u {EMAIL}:{APIKEY}
//TBD

Example Response:

HTTP/1.1 204 No Content

This endpoint performs delete of the user and associated data:

Not deleted immediately

These data objects are deleted automatically (e.g. due to expiration), hence won’t be deleted right after user deletion:

Data associated with organization

Public components

If there is any public component, associated to the user and the component is used in not deleted flows of someone else, the user can not be deleted automaticaly – contact technical support.

Authorization

You can delete yourself only, unless you have TenantAdmin role. Contact support team to get this role.

HTTP Request

DELETE https://api.elastic.io/v2/users/{USER_ID}

URL Parameters

Parameter Description
USER_ID The ID of a user

SSH keys

Retrieve all keys

Example Request:

curl https://api.elastic.io/v2/sshkeys/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
TBD

Example Response:

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

[
    {
        "id": "589df8b024dbdd0e461fc309",
        "type": "sshkey",
        "attributes": {
            "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/v2/sshkeys/

Returns

Returns an ssh key’s metadata object if the call succeeded.

Add new key

Example Request:

    curl https://api.elastic.io/v2/sshkeys/ \
        -X POST \
        -u {EMAIL}:{APIKEY} \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' -d '
        {
            "type": "sshkey",
            "attributes": {
                "key": "ssh-rsa YOUR KEY GOES HERE,
                "title": "My New Key"
            }
        }'
TBD

Example Response:

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

    {
        "id": "589df8a924dbdd0e461fc308",
        "type": "sshkey",
        "attributes": {
            "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/v2/sshkeys/

Arguments

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

Returns

Returns an ssh key’s metadata object if the call succeeded.

Delete a key

Example Request:

curl https://api.elastic.io/v2/sshkeys/{KEY_ID} \
   -X DELETE
   -u {EMAIL}:{APIKEY}
TBD

Example Response:

HTTP/1.1 204 No Content

This endpoint delete specified ssh key

HTTP Request

DELETE https://api.elastic.io/v2/sshkeys/{KEY_ID}

URL Parameters

Parameter Description
KEY_ID Key ID

Teams

Get user’s teams

Example Request:

curl https://api.elastic.io/v2/teams/ \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json'
TBD

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "data":[
      {
         "attributes":{
            "name":"singleteam"
         },
         "id":"5508411b34e5ac0300000019",
         "type":"team",
         "relationships":{
            "users":{
               "data":[
                  {
                     "type":"user",
                     "id":"5508411b34e5ac0300000020"
                  }
               ]
            }
         }
      }
   ],
   "meta":{}
}

This endpoint retrieves list of user’s teams

HTTP Request

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

Returns

Returns teams metadata object if the call succeeded.

Create team

Example Request:

 curl https://api.elastic.io/v2/teams \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
       "data": {
            "attributes": {
                "name": "myteam"
            }
       }
   }'
TBD

Example Response:

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

{
   "data":[
      {
         "attributes":{
            "name":"myteam"
         },
         "id":"5508411b34e5ac0300000019",
         "type":"team",
         "relationships":{
            "users":{
               "data":[
                  {
                     "type":"user",
                     "id":"5508411b34e5ac0300000020"
                  }
               ]
            }
         }
      }
   ],
   "meta":{

   }
}

This endpoint creates new team for user

HTTP Request

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

Parameter Required Description
name no team name

Returns

Returns teams metadata object if the call succeeded.

Add user to a team

Example Request:

 curl https://api.elastic.io/v2/{team_id}/relationships/members \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
       "data": {
            "type": "user",
            "id": "{user_id}"
       }
   }'
TBD

Example Response:

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

{
   "data":[
      {
         "attributes":{
            "name":"{team_name}"
         },
         "id":"5508411b34e5ac0300000019",
         "type":"team",
         "relationships":{
            "users":{
               "data":[
                  {
                     "type":"user",
                     "id":"{user_id}"
                  }
               ]
            }
         }
      }
   ],
   "meta":{}
}

This endpoint adds user to a team

HTTP Request

POST https://api.elastic.io/v2/teams/{team_id}/relationships/members

Parameter Required Description
id yes user’s ID
type yes should be “user”

Returns

Returns teams metadata object if the call succeeded.

Remove user from a team

Example Request:

 curl https://api.elastic.io/v2/{team_id}/relationships/members \
   -X DELETE \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
       "data": {
            "type": "user",
            "id": "{user_id}"
       }
   }'
TBD

Example Response:

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

{
   "data":[
      {
         "attributes":{
            "name":"{team_name}"
         },
         "id":"5508411b34e5ac0300000019",
         "type":"team",
         "relationships":{
            "users":{
               "data":[
                  {
                     "type":"user",
                     "id":"{user_id}"
                  }
               ]
            }
         }
      }
   ],
   "meta":{}
}

This endpoint removes user from a team

HTTP Request

DELETE https://api.elastic.io/v2/teams/{team_id}/relationships/members

Parameter Required Description
id yes user’s ID
type yes should be “user”

Returns

Returns teams metadata object if the call succeeded.

Remove team

Example Request:

 curl https://api.elastic.io/v2/{team_id} \
   -X DELETE \
   -u {EMAIL}:{APIKEY}
TBD

Example Response:

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

{}

This endpoint removes a team. It will only be executed if team has no repositories.

HTTP Request

DELETE https://api.elastic.io/v2/teams/{team_id}

Returns

Returns empty body