NAV
curl Node.js

Introduction

Welcome to elastic.io. This documentation is a full reference for the REST API documentation v2. The API implements the JSON API specification. We encourage the reader to familiarise himself with the details of the JSON API specification.

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/v2/users/me \
   -u {EMAIL}:{APIKEY}

Status Codes

Success

The elastic.io API responds with following status codes upon successful requests:

Status Code Meaning
200 Ok – Successful HTTP requests
201 Created – requested resource has been created successfully

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 resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
409 The resource object’s type is not among the type(s) that constitute the collection represented by the endpoint or a POST request to create a resource with a client-generated ID that already exists..
410 Gone – The resouce requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many resources! Slown down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarialy offline for maintanance. Please try again later.

Components

Accessing and sharing components

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 all 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][component-descriptor-doc].

HTTP Request

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

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 available components).

Returns

Returns repositories metadata object if the call succeeded.

Retrieve a component by ID

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}

URL Parameters

Parameter Required Description
COMPONENT_ID Yes Component identifier

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.

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

URL Parameters

Parameter Required Description
COMPONENT_ID Yes Component identifier

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 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 user latest. More details can be find [here]#retrieve-a-component-descriptor).

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 Required Description
COMPONENT_ID Yes Component identifier
GIT_REVISION Yes Revision of the component’s build. Use latest to retrieve the descriptor of 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 a 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 resource allows you to create a component repository. A component repository always belongs to a team. If you don’t have any teams yet, please create a team first.

HTTP Request

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

Body Parameters

Parameter Required Description
type yes A value must be component
attributes.name yes Repository name
attributes.icon no Component icon as base64 string
relationships.team.data.id yes Team ID the repository to create for
relationships.team.data.type yes A value must be team

Returns

Returns component’s metadata object if the call succeeded.

Update component access

This resource allows you to changing component’s access level.

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": {}
}

HTTP Request

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

URL Parameters

Parameter Required Description
COMPONENT_ID Yes Component identifier

Access level

A component may have one of the following access level:

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.

Delete 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 resource allows you to delete a component. A component may only be delete if it not used in any flow.

HTTP Request

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

URL Parameters

Parameter Required Description
COMPONENT_ID yes Component ID

Authorization

The component must 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.

Retrieve 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": "{COMPONENT_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

URL Parameters

Parameter Required Description
COMPONENT_ID yes 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

Returns environment variables

Update 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": "{COMPONENT_ID}",
        "type": "component-env"
    },
    "meta": {}
}

This endpoint replaces env vars for given component.

HTTP Request

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

URL Parameters

Parameter Required Description
COMPONENT_ID yes Component ID

Body Parameters

Parameter Required Description
type yes A value must be component-env
attributes.vars yes JSON object representing environmental variables mapped to their values.

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

Credentials

Retrieve all credentials

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 resource allows you to retrieve all credentials belonging to the given user.

HTTP Request

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

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.

Retrieve a credential by ID

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 resource allows you to retrieve a credential by its identifier. If the credential with given ID does not belong to the current user an error is returned.

HTTP Request

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

URL Parameters

Parameter Required Description
CREDENTIAL_ID Yes Credential identifier

Returns

Returns a credential object if the call succeeded.

Create a 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 resource allows you to create a credential.

HTTP Request

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

Body Parameters

Parameter Required Description
type yes A value must 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 must be component
attributes.keys no An object which represents component’s configuration (OAuth keys, etc.)

Returns

Returns credential object if the call succeeded.

Update 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 resource allows you to update a credential.

HTTP Request

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

URL Parameters

Parameter Required Description
CREDENTIAL_ID yes Credential ID

Body Parameters

Parameter Required Description
id yes A value must be the same as URL parameter CREDENTIAL_ID
type yes A value must 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.

Data samples

Retrieve data sample

This resource allows you to retrieve data sample.

Example Request:

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

Example Response:

{
    "data": {
        "id": "{DATASAMPLE_ID}",
        "type": "data-sample",
        "links": {
            "self": "/v2/data-samples/585d389b90ea62ce348a478b"
        },
        "relationships": {
            "component_version": {
                "data": {
                    "id": "latest",
                    "type": "version"
                },
                "links": {
                    "self": "/v2/components/5863f7136ef9da255ad9a9bc/versions/latest"
                }
            },
            "component": {
                "data": {
                    "id": "5863f7136ef9da255ad9a9bc",
                    "type": "component"
                },
                "links": {
                    "self": "/v2/components/5863f7136ef9da255ad9a9bc"
                }
            },
            "user": {
                "data": {
                    "id": "585d389b90ea62ce348a478b",
                    "type": "user"
                },
                "links": {
                    "self": "/v2/users/${client.id}"
                }
            }
        },
        "attributes": {
            "method": "hello123",
            "result": {
                "foo": "bar1",
                "baz": "qwe1"
            }
        }
    },
    "meta": {}
}

Authorization

A member of an organization can get any sample from own organization. User without organization can get only own samples.

HTTP Request

GET https://api.elastic.io/v2/data-samples/{DATASAMPLE_ID}

Create data sample

Example Request:

 curl https://api.elastic.io/v2/data-samples \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
        "data": {
            "type": "data-sample",
            "attributes": {
                "method": "hello123",
                "result": {
                    "foo": "bar",
                    "baz": "foo"
                }
            },
            "relationships": {
                "component": {
                    "data": {
                        "id": "5863f7136ef9da255ad9a9bc",
                        "type": "component"
                    }
                },
                "component_version": {
                    "data": {
                        "id": "latest",
                        "type": "version"
                    }
                }
            }
        }
    }'
 TBD

Example Response:

{
    "data": {
        "id": "585d389b90ea62ce348a478b",
        "type": "data-sample",
        "links": {
            "self": "/v2/data-samples/585d389b90ea62ce348a478b"
        },
        "relationships": {
            "component_version": {
                "data": {
                    "id": "latest",
                    "type": "version"
                },
                "links": {
                    "self": "/v2/components/5863f7136ef9da255ad9a9bc/versions/latest"
                }
            },
            "component": {
                "data": {
                    "id": "5863f7136ef9da255ad9a9bc",
                    "type": "component"
                },
                "links": {
                    "self": "/v2/components/5863f7136ef9da255ad9a9bc"
                }
            },
            "user": {
                "data": {
                    "id": "585d389b90ea62ce348a478b",
                    "type": "user"
                },
                "links": {
                    "self": "/v2/users/${client.id}"
                }
            }
        },
        "attributes": {
            "method": "hello123",
            "result": {
                "foo": "bar1",
                "baz": "qwe1"
            }
        }
    },
    "meta": {}
}

HTTP Request

POST https://api.elastic.io/v2/data-samples

Body Parameters

Parameter Required Description
type yes A value must be data-sample
attributes.method yes Component’s action or trigger name.
attributes.result yes Data sample body
relationships.component.data.id yes Component’s id
relationships.component_version.data.id yes Revision of the component’s build. Use latest to retrieve the descriptor of the most recent successful build.

Returns

Returns data sample object if the call succeeded.

Flows

Retrieve all flows

Example Request:

 curl https://api.elastic.io/v2/flows?page[size]=20&page[number]=1 \
   -g \
   -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 resource allows you to retrieve flows.

HTTP Request

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

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 the given user. If the user is a member of an organization, all the flows of the organization are returned. If the user is a member in multiple organizations, the given API key is used to match the proper 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 resource allows you to retrieve a flow by its identifier. If the flow with given ID does not belong to the current user or to one of his organizations, an error is returned.

HTTP Request

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

URL Parameters

Parameter Required Description
FLOW_ID Yes Flow identifier

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",
          "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 resource allows you to create a new flow.

HTTP Request

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

Body Parameters

Parameter Required Description
type yes A value must be flow
attributes.name yes Flow name
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

Update a flow

Example request

curl https://api.elastic.io/v2/flows/{FLOW_ID} \
   -X PATCH \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
          "data": {
            "type": "flow",
            "id": "{FLOW_ID}",
            "attributes": {
              "name": "this is a test task"
            }
          }
    }'

TBD

Example response

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

{
  "data": {
    "id": "58f07f67401e5f0019275306",
    "type": "flow",
    "links": {
      "self": "/v2/flows/58f07f67401e5f0019275306"
    },
    "attributes": {
      "name": "this is a test task",
      "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": {
                "textBody": "{{fireTime}}",
                "subject": "Test",
                "to": "info@acme.org"
              }
            }
          }
        ]
      },
      "api_version": "2.0"
    },
    "relationships": {
      "user": {
        "data": {
          "id": "58c91bd02e669f0019243fdf",
          "type": "user"
        },
        "links": {
          "self": "/v2/users/58c91bd02e669f0019243fdf"
        }
      },
      "organization": {
        "data": {
          "id": "57595b65cc6b4b0000000003",
          "type": "organization"
        },
        "links": {
          "self": "/v2/organizations/57595b65cc6b4b0000000003"
        }
      }
    }
  },
  "meta": {}
}

This resource allows you to update the given flow.

HTTP Request

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

URL Parameters

Parameter Required Description
FLOW_ID yes Flow ID

Body Parameters

Parameter Required Description
type yes A value must be flow
id yes ID of the flow you want to update
attributes.name no Flow name
attributes.type no Flow type. May be any of: ordinary, long_running
attributes.graph no Flow graph representing component connections
attributes.cron no Cron expression representing flow timing

Returns

Returns the updated flow

Start a flow

Example request

curl https://api.elastic.io/v2/flows/{FLOW_ID}/start \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json'
TBD

Example response

HTTP/1.1 202 Accepted

This endpoint starts a flow with given ID.

HTTP Request

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

URL Parameters

Parameter Required Description
FLOW_ID Yes Flow identifier

Returns

Empty response

Stop a flow

Example request

curl https://api.elastic.io/v2/flows/{FLOW_ID}/stop \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json'
TBD

Example response

HTTP/1.1 202 Accepted

This endpoint stops a flow with given ID.

HTTP Request

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

URL Parameters

Parameter Required Description
FLOW_ID Yes Flow identifier

Returns

Empty response

Delete a flow

Example Request:

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

This resource allows you to delete a flow.

HTTP Request

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

URL Parameters

Parameter Required Description
FLOW_ID yes Flow ID

Example Response:

HTTP/1.1 204 No Content

Lookup tables

Retrieve all lookup tables

This resource allows you to retrieve all 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": {}
}

HTTP Request

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

Create a 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": {}
}

HTTP Request

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

Body Parameters

Parameter Required Description
type yes A value must be lookup
attributes.title yes Lookup table title.
attributes.data yes A JSON object representing a lookup table

Update a lookup table

Example Request:

 curl https://api.elastic.io/v2/lookups/{LOOKUP_ID} \
   -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

This resource allows you to update a lookup table.

HTTP Request

PUT https://api.elastic.io/v2/lookups

URL Parameters

Parameter Required Description
LOOKUP_ID yes Lookup table ID

Body Parameters

Parameter Required Description
type yes A value must be lookup
attributes.title yes Lookup table title.
attributes.data yes A JSON object representing a lookup table

Delete a lookup table

Example Request:

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

This resource allows you to delete a lookup table.

HTTP Request

DELETE https://api.elastic.io/v2/lookups/{LOOKUP_ID}

URL Parameters

Parameter Required Description
LOOKUP_ID yes Lookup table ID

Example Response:

HTTP/1.1 204 No Content

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).

Scheduled Executions

Preamble

What are scheduled executions?

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. Please see how to poll execution results.
  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. Please see how to poll execution results.
  4. The results are retrieved from exec/result/{EXECUTION_ID}. Please see how to retrieve execution results.

Scheduled Executions

Verify credentials

Example Request:

 curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/verify-credential \
 -u {EMAIL}:{APIKEY} \ 
 -X POST -H 'Content-Type: application/json' -d '
 {
     "data": {
         "type": "verify-credential",
         "attributes": {
             "module": "getHello",
             "fields": {
                 "apiKey" : "secret"
             }
         }
     }
 }'
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"
        }
    }
}

This resource allows you to verify credentials. The verification credential is an asynchronous process because it is accomplished by sending a request to an external API. The entire process is described here. This page describes how to perform the 1st step of this process. Please also read details on polling execution results and retrieving execution results.

HTTP Request

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

Authorization

The component should be accessible to the client.

URL Parameters

Parameter Required Description
COMPONENT_ID yes Name of a component’s module.
GIT_REVISION Yes Revision of the component’s build. For available versions see here. For latest version use latest.

Body Parameters

Parameter Required Description
module yes Name of the component’s module as defined in component.json
keys Yes An object which represents the configuration of credential. The semantics are same as in creating a credential.

Retrieve component’s metamodel

Example Request:

curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/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"
        }
    }
}

This resource allows you to retrieve component’s metamodel. The retrieval of metamodel is an asynchronous process because it is accomplished by sending a request to an external API. The entire process is described here. This page describes how to perform the 1st step of this process. Please also read details on polling execution results and retrieving execution results.

HTTP Request

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

Authorization

The component should be accessible to the client.

URL Parameters

Parameter Required Description
COMPONENT_ID yes Name of a component’s module.
GIT_REVISION Yes Revision of the component’s build. For available versions see here. For latest version use latest.

Body Parameters

Parameter Required Description
type yes A value must be dynamic-metadata
attributes.module yes Name of the component’s module as defined in component.json
attributes.fields Yes Contains values for component’s fields. Semantics are same as defining fields for a node in a flow graph.
relationships.credential.id No If credentials are specified in the component’s descriptor, create a credential first and use its id.
relationships.credential.type No If credentials are specified in the component’s descriptor, value credential must be used here.

Retrieve component’s select model

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"
        }
    }
}

This resource allows you to retrieve component’s select model. The retrieval of select model is an asynchronous process because it is accomplished by sending a request to an external API. The entire process is described here. This page describes how to perform the 1st step of this process. Please also read details on polling execution results and retrieving execution results.

HTTP Request

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

Authorization

The component should be accessible to the client.

URL Parameters

Parameter Required Description
COMPONENT_ID yes Name of a component’s module.
GIT_REVISION Yes Revision of the component’s build. For available versions see here. For latest version use latest.

Body Parameters

Parameter Required Description
type yes A value must be select-model
attributes.module yes Name of the component’s module as defined in component.json
attributes.fields Yes Contains values for component’s fields. Semantics are same as defining fields for a node in a flow graph.
relationships.credential.id No If credentials are specified in the component’s descriptor, create a credential first and use its id.
relationships.credential.type No If credentials are specified in the component’s descriptor, value credential must be used here.

Poll a result of an execution

Example Request:

curl https://api.elastic.io/v2/exec/poll/{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": {},
            "status": "Pending request, waiting other process"
        },
        "links": {
            "self": "/v2/exec/result/58becb8059a65f18c5c60e41"
        }
    },
    "meta": {}
}

Response “Result ready”:

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

{
    "data": {},
    "meta": {}
}

This resource allows you to poll a result of an execution. Once the execution is done, the endpoint responds with HTTP 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 Required Description
COMPONENT_ID yes Name of a component’s module.
GIT_REVISION Yes Revision of the component’s build. For available versions see here. For latest version use latest.

Response status codes

Status Code Header Description
200 - The execution is still in progress.
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)

Retrieve 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 Required Description
EXECUTION_ID yes Execution identifier.

Response status codes

Status Code Description
200 The execution result is ready.
409 The execution result is not ready yet.

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.

SSH keys

Retrieve all SSH 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

{
    "data": [
        {
            "id": "589df8b024dbdd0e461fc309",
            "type": "sshkey",
            "attributes": {
                "title": "My Key",
                "fingerprint": "fingerprint",
                "user_id": "user_id",
                "key":"ssh_key"
            }
        }
    ]
}

This resource allows you to retrieve all SSH keys of the current user.

HTTP Request

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

Returns

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

Create a new SSH 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 resource allows you to create a new SSH key.

HTTP Request

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

Body Parameters

Parameter Required Description
type yes A value must be sshkey
attributes.key yes A valid RSA or DSA SSH public key.
attributes.title no Title of the key

Returns

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

Delete a SSH 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 resource allows you to delete a SSH key.

HTTP Request

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

URL Parameters

Parameter Required Description
KEY_ID yes SSH key ID

Teams

Retrieve all 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 resource allows you to retrieve all teams the current user is member in.

HTTP Request

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

Returns

Returns teams metadata object if the call succeeded.

Create a 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 resource allows you to create a new team.

HTTP Request

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

Body Parameters

Parameter Required Description
type yes A value must be team
attributes.name no A team name.

Returns

Returns teams metadata object if the call succeeded.

Add a new member to a team

Example Request:

 curl https://api.elastic.io/v2/teams/{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":"myteam"
         },
         "id":"5508411b34e5ac0300000019",
         "type":"team",
         "relationships":{
            "users":{
               "data":[
                  {
                     "type":"user",
                     "id":"{USER_ID}"
                  }
               ]
            }
         }
      }
   ],
   "meta":{}
}

This resource allows you to add a new member to a team.

HTTP Request

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

URL Parameters

Parameter Required Description
TEAM_ID yes Team identifier

Body Parameters

Parameter Required Description
type yes A value must be user
id yes Id of an already registered user, who will be added as a member of the team

Returns

Returns teams metadata object if the call succeeded.

Remove a member from a team

Example Request:

 curl https://api.elastic.io/v2/teams/{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":"myteam"
         },
         "id":"5508411b34e5ac0300000019",
         "type":"team",
         "relationships":{
            "users":{
               "data":[
                  {
                     "type":"user",
                     "id":"{user_id}"
                  }
               ]
            }
         }
      }
   ],
   "meta":{}
}

This resource allows you to remove a member from a team.

HTTP Request

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

URL Parameters

Parameter Required Description
TEAM_ID yes Team identifier

Body Parameters

Parameter Required Description
type yes A value must be user
id yes User identifier

Returns

Returns teams metadata object if the call succeeded.

Delete a team

Example Request:

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

Example Response:

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

{}

This resource allows you to delete a team.

HTTP Request

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

URL Parameters

Parameter Required Description
TEAM_ID yes Team ID

Returns

Returns 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 resource allows you to retrieve your user.

HTTP Request

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

Returns

Returns a user object if the call succeeded.

Retrieve a user by ID

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 resource allows you to retrieve a user by ID.

HTTP Request

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

URL Parameters

Parameter Required Description
USER_ID yes User identifier

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.

Retrieve all users

Example Request (with paging):

curl https://api.elastic.io/v2/users/?page[size]=1&page[number]=5 \
   -g \
   -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/

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"
            },
            "relationships": {
                "organizations": {
                    "data": [
                        {"id": "54f4be3fe7d5224f91000001"}
                    ]
                }
            }
        }
    }'
//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 resource allows you to create a user.

HTTP Request

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

Body Parameters

Parameter Required Description
type yes A value must be user
attributes.first_name yes User’s first name.
attributes.last_name yes User’s last name.
attributes.email yes User’s email.
attributes.password yes User’s password.
attributes.company no User’s company.
relationships.organizations.data yes Organizations to join.

Authorization

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

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 resource allows you to delete a user. When a user is delete following data are deleted as well:

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 Required Description
USER_ID yes User identifier