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 – The server cannot or will not process the request due to an apparent client error |
| 401 | Unauthorized – Your API key is wrong |
| 403 | Forbidden – The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource |
| 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 resource requested has been removed from our servers |
| 418 | I’m a teapot |
| 429 | Too Many Requests – You’re requesting too many resources! Slow down! |
| 500 | Internal Server Error – We have a problem with our server. Try again later |
| 503 | Service Unavailable – We’re temporarily offline for maintenance. Please try again later |
Agents
Retrieve all agents
Example Request:
curl https://api.elastic.io/v2/agents?workspace_id={WORKSPACE_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"{AGENT_ID}",
"type":"agent",
"links":{
"self":"/v2/agents/{AGENT_ID}"
},
"attributes":{
"title":"agent title",
"status":"online",
"last_seen":"2017-10-04T19:02:19.188Z"
},
"relationships":{
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/{WORKSPACE_ID}"
}
}
}
}
],
"meta":{}
}
This resource allows you to retrieve all the agents belonging to the given Workspace.
HTTP Request
GET https://api.elastic.io/v2/agents?workspace_id={WORKSPACE_ID}
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| workspace_id | yes | An Id of the Workspace |
Returns
Returns all the agents belonging to the given Workspace.
Сreate agent
Example Request:
curl https://api.elastic.io/v2/agents \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"agent",
"attributes":{
"title":"agent title",
"description":"agent description"
},
"relationships":{
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 OK
Content-Type: application/json
{
"data":{
"id":"{AGENT_ID}",
"type":"agent",
"links":{
"self":"/v2/agents/{AGENT_ID}"
},
"attributes":{
"title":"agent title",
"description":"agent description",
"status":"pending"
},
"relationships":{
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/{WORKSPACE_ID}"
}
}
}
},
"meta":{}
}
This resource allows you to create a new agent. The agent is created in pending state and our support is informed about it.
We will contact you within 2-3 working days.
HTTP Request
POST https://api.elastic.io/v2/agents/
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value must be agent |
| attributes.title | yes | Agent title |
| attributes.description | yes | Agent description |
| relationships.workspace.data.id | yes | An Id of the Workspace |
| relationships.workspace.data.type | yes | A value must be workspace |
Returns
Returns the created agent object.
Components
Accessing and sharing components
Each Component belongs to a Team. Each User who is a member of the team 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:
team– no sharing. Only Contract members can use the component.tenant– component could be used by the other clients in the tenant.global– special mode for components from the standard set of components of Elastic.io Platform (e.g.Timer,Webhooketc). Any user of the platform can useglobalcomponents.
Accordingly, a set of components, available for each user is consist of: not shared components from the user’s Contract, components with tenant access and global components.
Retrieve all components
Example Request:
curl https://api.elastic.io/v2/components?contract_id={CONTRACT_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"{COMPONENT_ID}",
"type":"component",
"links":{
"self":"/v2/components/{COMPONENT_ID}"
},
"attributes":{
"name":"name",
"team_name":"team_name",
"access": "tenant"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{COMPONENT_ID}/versions"
}
},
"latest_version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/latest"
}
}
}
}
],
"meta":{},
"included":[
{
"id":"{GIT_REVISION}",
"type":"version",
"links":{
"self":"/v2/versions/{GIT_REVISION}"
},
"attributes":{
"date":1517392057184,
"version_number":69
},
"relationships":{
"descriptor":{
"data":{
"id":"0eff1d1a46b78ba1f468982e16d0382e8a91280d",
"type":"descriptor"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
}
},
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}"
}
}
}
},
{
"id":"0eff1d1a46b78ba1f468982e16d0382e8a91280d",
"type":"descriptor",
"links":{
"self":"/v2/descriptors/0eff1d1a46b78ba1f468982e16d0382e8a91280d"
},
"attributes":{
"repo_name":"repo_name",
"team_name":"team_name",
"short_revision":"0eff1d1",
"is_latest":true,
"description":"desc",
"icon":"BASE64",
"language":"nodejs",
"sailor_version":"2.1.6",
"title":"Data mapper",
"service":"mapper",
"actions":{
"map":{
"title":"Mapper",
"main":"./map.js"
},
"jsonataMap":{
"title":"Jsonata mapper",
"main":"./jsonata_map.js"
}
},
"fields":{
"mapper":{
"viewClass":"MapperView"
}
}
},
"relationships":{
"version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/{COMPONENT_ID}/versions/{GIT_REVISION}"
}
}
}
}
],
"links":{
"self":"/v2/components"
}
}
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?contract_id={CONTRACT_ID}
HTTP Request with parameters
GET https://api.elastic.io/v2/components?contract_id={CONTRACT_ID}&filter[access]=private
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| contract_id | yes (only for Tenant Admin) | An Id of the Contract |
| filter[access] | No | Allowed values: private (only components from own Contract returned), public (only shared components from the other Contracts) 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'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{COMPONENT_ID}",
"type":"component",
"links":{
"self":"/v2/components/{COMPONENT_ID}"
},
"attributes":{
"name":"component name",
"team_name":"{team_name}",
"access": "team"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{COMPONENT_ID}/versions"
}
},
"latest_version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/latest"
}
}
}
},
"meta":{},
"included":[
{
"id":"{GIT_REVISION}",
"type":"version",
"links":{
"self":"/v2/versions/{GIT_REVISION}"
},
"attributes":{
"date":1513183339032,
"version_number":7
},
"relationships":{
"descriptor":{
"data":{
"id":"{GIT_REVISION}",
"type":"descriptor"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
}
},
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}"
}
}
}
},
{
"id":"{GIT_REVISION}",
"type":"descriptor",
"links":{
"self":"/v2/descriptors/{GIT_REVISION}"
},
"attributes":{
"repo_name":"repo_name",
"team_name":"team_name",
"short_revision":"df7cf1d",
"is_latest":true,
"description":"desc",
"icon":"BASE64",
"language":"nodejs",
"sailor_version":"2.2.1",
"title":"title",
"actions":{
"update":"<Actions Object>"
},
"triggers":{
"select":"<Triggers Object>"
},
"credentials":{
"fields":{
"apiKey":{
"label":"API key",
"required":true,
"viewClass":"TextFieldWithNoteView",
"note":"{note}"
}
}
}
},
"relationships":{
"version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/{COMPONENT_ID}/versions/{GIT_REVISION}"
}
}
}
}
]
}
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 Contract or shared one).
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'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"{GIT_REVISION}",
"type":"version",
"links":{
"self":"/v2/versions/{GIT_REVISION}"
},
"attributes":{
"date":1508754889997,
"version_number":1
},
"relationships":{
"descriptor":{
"data":{
"id":"{GIT_REVISION}",
"type":"descriptor"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
}
},
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}"
}
}
}
}
],
"meta":{},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions"
}
}
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 Contract or shared one).
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'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{GIT_REVISION}",
"type":"descriptor",
"links":{
"self":"/v2/descriptors/{GIT_REVISION}"
},
"attributes":{
"repo_name":"repo_name",
"team_name":"team_name",
"short_revision":"cf0a2d9",
"is_latest":true,
"description":"desc",
"icon":"BASE64",
"language":"nodejs",
"sailor_version":"2.2.1",
"title":"title",
"actions":{
"update":"<Actions Object>"
},
"triggers":{
"select":"<Triggers Object>"
},
"credentials":{
"fields":{
"apiKey":{
"label":"API key",
"required":true,
"viewClass":"TextFieldWithNoteView",
"note":"note"
}
}
}
},
"relationships":{
"version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/{COMPONENT_ID}/versions/{GIT_REVISION}"
}
}
}
},
"meta":{}
}
This endpoint retrieves an information about single component by it’s ID and/or version,
for latest version use latest. More details can be find here.
HTTP Request
GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor
or
GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/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 Contract or shared one).
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}"
}
},
"contract":{
"data":{
"type":"contract",
"id":"{CONTRACT_ID}"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"{REPOSITORY_ID}",
"type":"component",
"links":{
"self":"/v2/components/{REPOSITORY_ID}"
},
"attributes":{
"name":"{REPOSITORY_NAME}",
"team_name":"{TEAM_NAME}",
"access": "team"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{REPOSITORY_ID}/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 |
| relationships.contract.data.id | no | Contract ID the repository to create for |
| relationships.contract.data.type | no | A value must be contract |
Authorization
This request is authorized to a user with contracts.repository.edit permission.
Returns
Returns component’s metadata object if the call succeeded.
Update component access
This resource allows you to changing component’s access level from team to tenant.
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"
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{COMPONENT_ID}",
"type":"component",
"links":{
"self":"/v2/components/{COMPONENT_ID}"
},
"attributes":{
"name":"name",
"team_name":"team_name",
"access": "tenant"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{COMPONENT_ID}/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:
team– no sharing. Only team members can use the component.tenant– component could be used by the other clients in the tenant.global– special mode for components from the standard set of components of Elastic.io Platform (e.g.Timer,Webhooketc). Any user of the platform can useglobalcomponents.
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}
Example Response:
HTTP/1.1 204 No Content
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
This request is authorized to a user with contracts.repository.edit permission. The component must belong to one of the client’s team.
Returns
204 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'
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",
"links":{
"self":"/v2/component-envs/{COMPONENT_ID}"
}
},
"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).
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"
}
}
}
}'
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",
"links":{
"self":"/v2/component-envs/{COMPONENT_ID}"
}
},
"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).
Returns
Returns environment variables
Contracts
What is a Contract unit?
A Contract is a fundamental entity (scope) that reflects an agreement between a customer and the platform’s provider. The Contract scope can have an unlimited number of members, workspaces, and development teams. It also serves as a singular entity for the billing department against the consumed resources by all the integration flows. Every member of the Contract’s scope has a specific access level or role within the current Contract. To get all available roles, please execute the “Get the Contract’s roles” endpoint. The same user can have different roles in different Contracts within the Platform. Every Contract must have at least one Owner. The Owner’s Role has a predefined/default permissions’ set. It means this role cannot be deleted and the permissions’ set cannot be changed.
Please note that the Tenant Admin creates a Contract along with the Contract’s Owner. Once it’s done the Contract’s Owner will be able to invite other Users as well as assigning the necessary roles for them. (Tenant is a higher scope in the Platform’s hierarchy. It includes all the Contracts that belong to the white-label client).
Create a Contract
Example Request:
curl https://api.elastic.io/v2/contracts \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"contract",
"attributes":{
"name":"My Contract",
"available_roles":[
{
"scope":"contracts",
"role":"admin"
},
{
"scope":"workspaces",
"role":"admin"
}
]
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"{CONTRACT_ID}",
"type":"contract",
"links":{
"self":"/v2/contracts/{CONTRACT_ID}"
},
"attributes":{
"name":"My Contract",
"available_roles":[
{
"role":"admin",
"scope":"contracts"
},
{
"role":"owner",
"scope":"contracts"
},
{
"role":"admin",
"scope":"workspaces"
},
{
"role":"owner",
"scope":"workspaces"
}
],
"status":"active"
}
},
"meta":{}
}
This endpoint allows creating a Contract.
HTTP Request
POST https://api.elastic.io/v2/contracts
Authorization
This request is authorized to only a user with TenantAdmin role. Contact support team to get this role.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “contract” |
| attributes.name | yes | Name of the Contract |
| attributes.available_roles[] | no | The subset of Tenants roles the particular Contract belongs to |
Returns
Returns Contract object if the call succeeded
Update a Contract
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID} \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"contract",
"id":"{CONTRACT_ID}"
"attributes":{
"name":"New Contract Name",
"available_roles":[
{
"scope":"contracts",
"role":"admin"
},
{
"scope":"workspaces",
"role":"admin"
},
{
"scope":"workspaces",
"role":"guest"
}
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{CONTRACT_ID}",
"type":"contract",
"links":{
"self":"/v2/contracts/{CONTRACT_ID}"
},
"attributes":{
"name":"New Contract Name",
"available_roles":[
{
"role":"admin",
"scope":"contracts"
},
{
"role":"owner",
"scope":"contracts"
},
{
"role":"admin",
"scope":"workspaces"
},
{
"role":"guest",
"scope":"workspaces"
},
{
"role":"owner",
"scope":"workspaces"
}
],
"status":"active"
}
},
"meta":{}
}
This endpoint allows to change Contracts’ name and to update available roles in the Contract.
HTTP Request
PATCH https://api.elastic.io/v2/contracts/{CONTRACT_ID}
Authorization
For updating Contract name this request is authorized to the users with contracts.contract.edit permission. For updating the set of available roles of the particular Contract this request is authorized to the user with TenantAdmin role. Contact support team to get this role.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “contract” |
| attributes.name | yes | Name of the Contract |
| attributes.available_roles[] | no | The subset of Tenants roles the particular Contract belongs to |
Returns
Returns Contract object if the call succeeded
Get Contract by Id
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}?include=members,invites \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5b4f3e093a472b0006c71d47",
"type":"contract",
"links":{
"self":"/v2/contracts/5b4f3e093a472b06c71d47"
},
"attributes":{
"name":"LucontractOne",
"available_roles": [],
"status": "active"
},
"relationships":{
"members":{
"data":[
{
"id":"59d22eeb865b0018adc248",
"type":"contract-member"
},
{
"id":"5a1c298abe7a00189caf76",
"type":"contract-member"
}
],
"links":{
"self":"/v2/contracts/5b4f3e093a472b06c71d47/members/"
}
},
"invites":{
"data":[
{
"id":"5b6d8ce8033b0011fef43e",
"type":"contract-invite"
}
],
"links":{
"self":"/v2/contracts/5b4f3e093a4b0006c71d47/invites/"
}
}
}
},
"meta":{},
"included":[
{
"id":"59d22e7eebrr5b0018adc248",
"type":"contract-member",
"attributes":{
"first_name":"Alla",
"last_name":"Ospik",
"roles":[
"admin"
],
"email":"alla.ospik@elastic.io"
},
"relationships":{
"user":{
"data":{
"id":"59d22e7eeb865bee18adc248",
"type":"user"
},
"links":{
"self":"/v2/users/59d22e7eeb865bee18adc248"
}
}
}
},
{
"id":"5a1c298a75be7aee189caf76",
"type":"contract-member",
"attributes":{
"first_name":"Henry",
"last_name":"Pushkin",
"roles":[
"admin"
],
"email":"henry@elastic.io"
},
"relationships":{
"user":{
"data":{
"id":"5a1c298a75be7aee189caf76",
"type":"user"
},
"links":{
"self":"/v2/users/5a1c298a75be7aee189caf76"
}
}
}
}
],
"links":{
"self":"/v2/contracts/5b4f3e093a472b0ee6c71d47"
}
}
This endpoint returns a Contract object for a specific contract’s id.
HTTP Request
GET https://api.elastic.io/v2/contracts/CONTRACT_ID/
Authorization
A client has to be a member of the Contract’s scope or belong to the Tenant Admin users group (please contact our support department to get this specific role).
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
URL Query Parameters
| Parameter | Required | Description |
|---|---|---|
| include | no | You may add a parameter, such as the ‘include’ for more detailed information regarding the Workspace’s entities. Possible values are members and/or invites. |
Get Contracts
Example Request:
curl https://api.elastic.io/v2/contracts/
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"5b4f3379ff4305510483ba1a",
"type":"contract",
"links":{
"self":"/v2/contracts/5b4f3379ff4304655483ba1a"
},
"attributes":{
"name":"LuzhaOrg",
"available_roles": [],
"status": "active"
},
"relationships":{
"members":{
"data":[
{
"id":"5967519b2d8ff5501871dc39",
"type":"contract-member"
},
{
"id":"59bfb6958aa5555519ab26f1",
"type":"contract-member"
},
{
"id":"59d22e7eeb865b558adc248",
"type":"contract-member"
}
],
"links":{
"self":"/v2/contracts/5b4f3379ff455610483ba1a/members/"
}
}
}
},
{
"id":"5b76b1e104da8244038d5c9",
"type":"contract",
"links":{
"self":"/v2/contracts/5b76b1e104da82441038d5c9"
},
"attributes":{
"name":"FridayContract",
"available_roles": [],
"status": "active"
},
"relationships":{
"members":{
"data":[
{
"id":"5773e8e26e05f10ert0000003",
"type":"contract-member"
},
{
"id":"59d22e7eeb865berrt18adc248",
"type":"contract-member"
}
],
"links":{
"self":"/v2/contracts/5b76b1e104daer001038d5c9/members/"
}
}
}
}
],
"meta":{}
}
This endpoint returns all the Contract’s objects for a specific user.
HTTP Request
GET https://api.elastic.io/v2/contracts/
Authorization
A client has to be a member of the Contract’s scope.
Get a list of members of the Contract’s scope
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members/ \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"59d22e7eeb865bee18adc248",
"type":"contract-member",
"attributes":{
"first_name":"Hanna",
"last_name":"Yutsenko",
"roles":[
"admin"
],
"email":"hanna.yutsenko@elastic.io"
},
"relationships":{
"user":{
"data":{
"id":"59d22e7eeb86544018adc248",
"type":"user"
},
"links":{
"self":"/v2/users/59d22e7eeb865b4418adc248"
}
}
}
},
{
"id":"5a1c298a75be7a44489caf76",
"type":"contract-member",
"attributes":{
"first_name":"Ksu",
"last_name":"Luzha",
"roles":[
"admin"
],
"email":"margarita@elastic.io"
},
"relationships":{
"user":{
"data":{
"id":"5a1c298a75be7a44189caf76",
"type":"user"
},
"links":{
"self":"/v2/users/5a1c298a75be7a44189caf76"
}
}
}
}
],
"meta":{},
"links":{
"self":"/v2/contracts/5b4f3e093a47244006c71d47/members"
}
}
This endpoint returns a list of all members of a specific Contract’s scope.
HTTP Request
GET https://api.elastic.io/v2/contracts/CONTRACT_ID/members/
Authorization
A client has to be a member of the Contract’s scope.
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
Get a list of pending members (invites) of the Contract’s scope
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/invites/ \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [
{
"id": "5b6d663b033b550011fef351",
"type": "contract-invite",
"attributes": {
"email": "admin@elastic.io",
"roles": [
"admin"
]
}
},
{
"id": "5b83c0462e7785501158b654",
"type": "contract-invite",
"attributes": {
"email": "member@elastic.io",
"roles": [
"member"
]
}
},
{
"id": "5b855b333a667d5510ce4465",
"type": "contract-invite",
"attributes": {
"email": "member@elastic.io",
"roles": [
"member"
]
}
}
],
"meta": {}
}
This endpoint returns a list of pending members (invites) for a specific Contract’s scope.
HTTP Request
GET https://api.elastic.io/v2/contracts/CONTRACT_ID/invites/
Authorization
A client has to be a member of the Contract’s scope.
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
Get the Contract’s roles
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/roles/ \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{CONTRACT-POLICY_ID}",
"type":"contract-policy",
"attributes":{
"roles":[
{
"i18n":{
"en":"Admin"
},
"role":"admin",
"permissions":[
"contracts.membership.edit",
"contracts.workspace.create",
"contracts.workspace.listAll",
"contracts.workspace.delete",
"contracts.repository.edit",
"contracts.devTeam.edit"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Member"
},
"role":"member",
"permissions":[
"contracts.workspace.create"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Admin"
},
"role":"admin",
"permissions":[
"workspaces.workspace.edit",
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
},
{
"i18n":{
"en":"Integrator"
},
"role":"integrator",
"permissions":[
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
},
{
"i18n":{
"en":"Guest"
},
"role":"guest",
"permissions":[],
"scope":"workspaces"
},
{
"i18n":{
"en":"Custom_role"
},
"role":"custom_role",
"permissions":[
"workspaces.flow.edit",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
},
{
"i18n":{
"en":"Custom_role"
},
"role":"custom_role",
"permissions":[
"contracts.workspace.create",
"contracts.devTeam.edit"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Owner"
},
"role":"owner",
"permissions":[
"contracts.membership.edit",
"contracts.workspace.create",
"contracts.workspace.listAll",
"contracts.workspace.delete"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Owner"
},
"role":"owner",
"permissions":[
"workspaces.workspace.edit",
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
}
]
},
"relationships":{
"contract":{
"data":{
"id":"{CONTRACT_ID}",
"type":"contract"
},
"links":{
"self":"/v2/contracts/{CONTRACT_ID}"
}
}
}
},
"meta":{
}
}
This endpoint returns a list of the contract roles for a specific Contract’s scope.
HTTP Request
GET https://api.elastic.io/v2/contracts/CONTRACT_ID/roles/
Authorization
A client has to be a member of the Contract’s scope.
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
Invite a user to the Contract’s scope
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/invites/ \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "contract-invite",
"attributes": {
"email": "admin@elastic.io",
"roles": [
"owner"
],
"workspace_id":"{WORKSPACE_ID}",
"workspace_roles":[
"integrator"
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c20bd0376b463001053a6b5",
"type":"contract-invite",
"attributes":{
"email":"admin@elastic.io",
"roles":[
"owner"
],
"workspace_id":"{WORKSPACE_ID}",
"workspace_roles":[
"integrator"
]
}
},
"meta":{}
}
This endpoint allows inviting a user to Contract.
HTTP Request
POST https://api.elastic.io/v2/contracts/{CONTRACT_ID}/invites/
Authorization
This request is authorized for a Contract’s scope members with the permission contracts.membership.edit or the TenantAdmin role. To provide the workspase_id as an additional parameter user has to have permission workspaces.workspace.edit and belong to the provided Workspace.
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “contract-invite”. |
| attributes.email | yes | Email. |
| attributes.roles[] | yes | To get all available roles, please execute the “Get the Contract’s roles” endpoint. Note: The very first member of a contract must have owner role. |
| attributes.workspace_id | no | The id of the corresponding Workspace. |
| attributes.workspace_roles[] | no | To get all available roles, please execute the “Get the Contract’s roles” endpoint. |
Returns
Returns would invite the object if the call succeeded.
Returns 409 if Contract has no members and attributes.roles doesn’t contain owner role.
Add a new member to the Contract’s scope
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members/ \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "contract-member",
"id": "{USER_ID}",
"attributes": {
"roles": [
"{ROLE_1}",
"{ROLE_2}"
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"type":"contract-member",
"id":"588f832b87d7c33c7d5cc37a",
"attributes":{
"first_name":"Santos",
"last_name":"Mitchell",
"email":"Santos_Mitchell@example.com",
"roles": [
"{ROLE_1}",
"{ROLE_2}"
]
}
}
}
This endpoint allows adding a user to a certain Contract as a member. No invitation email message will be sent. The user becomes a member immediately.
HTTP Request
POST https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members
Authorization
This request is authorized for a user with the Tenant Admin role only. Please contact our support department to get this role.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| id | yes | id of an already registered user; the user will be added to the Contract’s scope as a member. |
| type | yes | A value should be “contract-member”. |
| attributes.roles[] | yes | To get all available roles, please execute the “Get the Contract’s roles” endpoint. Note: The very first member of a contract must have owner role. |
Returns
Returns Member’s object if the call succeeded.
Returns 409 if Contract has no members and attributes.roles doesn’t contain owner role.
Update membership in the Contract’s scope
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members/{USER_ID}/ \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "contract-member",
"id": "{USER_ID}",
"attributes": {
"roles": [
"{NEW_ROLE}"
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"59f747c33f1d3c001901a44e",
"type":"contract-member",
"links":{
"self":"/v2/members/59f747c33f1d3c001901a44e"
},
"attributes":{
"roles":[
"member"
]
}
},
"meta":{}
}
This endpoint allows updating membership of a given user. Only roles attribute can be updated.
HTTP Request
PATCH https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members/{USER_ID}/
Authorization
This request is authorized for the Contract’s members with the contracts.membership.edit permission.
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
| USER_ID | The ID of the user to be updated |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be the “contract-member”. |
| id | yes | id of an already registered user, must match the {USER_ID} URL param |
| attributes.roles[] | yes | To get all available roles, please execute the “Get the Contract’s roles” endpoint. |
Returns
Returns the member’s object if the call succeeded
Remove a member from the Contract’s scope.
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members/{USER_ID}/ \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
Removing User’s membership in the Contract’s scope.
HTTP Request
DELETE https://api.elastic.io/v2/contracts/{CONTRACT_ID}/members/{USER_ID}/
Authorization
This request is authorized for the contract’s scope members with the contracts.membership.edit permission and Tenant Admin role.
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the contract scope |
| USER_ID | The ID of the user that should leave the contract’s scope |
Returns
Responds with 204 No content message if the call succeeded (with empty body).
FAQ on Removing Contract Owner
Is it possible to remove an only member of the Contract with Owner role that hasn’t no another contracts? Yes. User also will be removed from the Platform at all.
Is it possible to remove a member of the Contract with Owner role if no other Contract Owner left? No. An error returns “You can not remove the last owner in the contract.”.
Is it possible to remove a member of the Contract with Owner role if any other Contract Owner left and this member hasn’t any another Contracts? Yes. User also will be removed from the Platform at all, Contract will work as before with another Owner.
Is it possible to remove an only member of the Contract with Owner role that has another Contracts. Yes. User will be removed from this Contract, but will stay the member of others Contracts.
Suspend Contract
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/suspend \
-X POST \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 202 Accepted
This endpoint allows suspending the Contract. The process is asynchronous. Suspending is completed once all of the flows in a given Contract will be stopped. While the Contract gets suspended, all the writing requests will be rejected.
HTTP Request
POST https://api.elastic.io/v2/contracts/CONTRACT_ID/suspend/
Authorization
A client has to have the Service Account record type or the TenantAdmin role (contact support team in getting this role).
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
Unsuspend Contract
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/unsuspend \
-X POST \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
This endpoint allows you to unsuspend the Contract.
HTTP Request
POST https://api.elastic.io/v2/contracts/CONTRACT_ID/unsuspend/
Authorization
A client has to have the Service Account record type or the TenantAdmin role (contact support team in getting this role).
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
Delete Contract
Example Request:
curl -i https://api.elastic.io/v2/contracts/{CONTRACT_ID} \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
The endpoint deletes a Contract’s scope along with everything it includes. These items are listed below:
- Accounts (Credentials)
- Agents
- DataSamples
- InviteTokens
- Flow’s DynamicMetadata
- Flow’s DynamicSelectModel
- Flow’s ExecStat
- Flow’s ExecutionResult
- Flow’s MarathonEvent
- Flow’s RequestBin
- Flow’s TaskHooksData
- Flow’s TaskStatError
- Flow’s TaskVersion
- Workspaces
- Teams
- Repos
- RepoBuilds
- User accounts who were only the members of the deleted Contract’s scope, as well as ssh keys associated with him/her.
Note, the deletion process is asynchronous. The actual data deletion will be performed after an API response, as it requires time for termination of all the Contract’s flows containers. * *A Contract cannot be deleted while any of its Components are being used in another Contract Flow
HTTP Request
DELETE https://api.elastic.io/v2/contracts/{CONTRACT_ID} \
Authorization
This request is authorized for members with the Tenant Admin role.
URL Parameters
| Parameter | Description |
|---|---|
| CONTRACT_ID | The ID of the Contract |
Returns
Responds with the 204 No content message if the call succeeded (with empty body).
Credentials
Retrieve all credentials
Example Request:
curl https://api.elastic.io/v2/credentials/?filter[component]={COMPONENT_ID}&workspace_id={WORKSPACE_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"meta":{},
"data":[
{
"id":"585430d3f02852a8a9fac45e",
"type":"credential",
"links":{
"self":"/v2/credentials/585430d3f02852a8a9fac45e"
},
"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"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
}
}
},
{
"id":"585430d3f02852a8a9fac45f",
"type":"credential",
"links":{
"self":"/v2/credentials/585430d3f02852a8a9fac45f"
},
"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"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
},
"agent":{
"data":{
"id":"59a410d76b670400182f190e",
"type":"agent"
},
"links":{
"self":"/v2/agents/59a410d76b670400182f190e"
}
}
}
}
}
],
"links":{
"self":"/v2/credentials"
}
}
This resource allows you to retrieve all credentials belonging to user’s Workspace.
HTTP Request
GET https://api.elastic.io/v2/credentials?workspace_id={WORKSPACE_ID}/
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| workspace_id | yes | An Id of the Workspace |
| 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'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"59f9f2ba112f28001921f274",
"type":"credential",
"links":{
"self":"/v2/credentials/59f9f2ba112f28001921f274"
},
"attributes":{
"name":"SFTP account",
"keys":{
"host":"sftp.company.org",
"username":"lord",
"password":"teststetr"
}
},
"relationships":{
"user":{
"data":{
"id":"59f747c33f1d3c001901a44e",
"type":"user"
},
"links":{
"self":"/v2/users/59f747c33f1d3c001901a44e"
}
},
"component":{
"data":{
"id":"56793fb4d8057406000000f7",
"type":"component"
},
"links":{
"self":"/v2/components/56793fb4d8057406000000f7"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
}
}
},
"meta":{}
}
This resource allows you to retrieve a credential by its identifier.
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/ \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"credential",
"attributes":{
"name":"credname",
"keys":{
"host":"hostname",
"username":"username",
"password":"pass"
}
},
"relationships":{
"component":{
"data":{
"id":"56793fb4d8057406000000f7",
"type":"component"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"5abe11edbec1cf00078b81d1",
"type":"credential",
"links":{
"self":"/v2/credentials/5abe11edbec1cf00078b81d1"
},
"attributes":{
"name":"credname",
"keys":{
"host":"hostname",
"username":"username",
"password":"pass"
}
},
"relationships":{
"user":{
"data":{
"id":"59d3562c68ed850019bde27f",
"type":"user"
},
"links":{
"self":"/v2/users/59d3562c68ed850019bde27f"
}
},
"component":{
"data":{
"id":"56793fb4d8057406000000f7",
"type":"component"
},
"links":{
"self":"/v2/components/56793fb4d8057406000000f7"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
},
"agent":{
"data":{
"id":"5a09deda2d5f49665afb739a",
"type":"agent"
},
"links":{
"self":"/v2/agents/5a09deda2d5f49665afb739a"
}
}
}
},
"meta":{}
}
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 |
| relationships.workspace.data.id | yes | The Workspace id this credential is for |
| relationships.workspace.data.type | yes | A value must be workspace |
| relationships.agent | no | The agent relation object |
| relationships.agent.data.id | no | The agent id this credential is for |
| relationships.agent.data.type | no | A value must be agent |
| attributes.keys | no | An object which represents component’s configuration (OAuth keys, etc.) |
Authorization
This request is authorized to only a user with workspaces.credential.edit permission
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"
}
},
"relationships": {
"agent": {
"data": {
"id": "59a410d76b670400182f190e",
"type": "agent"
}
}
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5aaff19dbd6d6400079b4624",
"type":"credential",
"links":{
"self":"/v2/credentials/5aaff19dbd6d6400079b4624"
},
"attributes":{
"name":"luzho4ek777",
"keys":{
"host":"sftp.company.org",
"username":"asssssa",
"password":"qweqweqw"
}
},
"relationships":{
"user":{
"data":{
"id":"59d3562c68ed850019bde27f",
"type":"user"
},
"links":{
"self":"/v2/users/59d3562c68ed850019bde27f"
}
},
"component":{
"data":{
"id":"56793fb4d8057406000000f7",
"type":"component"
},
"links":{
"self":"/v2/components/56793fb4d8057406000000f7"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
},
"agent":{
"data":{
"id":"5a09deda2d5f49665afb739a",
"type":"agent"
},
"links":{
"self":"/v2/agents/5a09deda2d5f49665afb739a"
}
}
}
},
"meta":{}
}
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. |
| relationships.agent | no | The agent relation object. Will remain untouched if omitted. |
| relationships.agent.data.id | no | The agent id this credential is for. |
| relationships.agent.data.type | no | A value must be agent |
Authorization
This request is authorized to only a user with workspaces.credential.edit permission
Returns
Returns a modified credential object if the call succeeded.
Delete a credential
Example Request:
curl https://api.elastic.io/v2/credentials/{CREDENTIAL_ID}/ \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
This resource allows you to delete a credential.
HTTP Request
DELETE https://api.elastic.io/v2/credentials/{CREDENTIAL_ID}/
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| CREDENTIAL_ID | yes | Credential ID |
Authorization
This request is authorized to only a user with workspaces.credential.edit permission
Returns
204 HTTP response code if the call succeeds, error otherwise.
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 Request with filter:
curl https://api.elastic.io/v2/data-samples?filter[id]={DATASAMPLE_ID1},{DATASAMPLE_ID2} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"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"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
},
"component":{
"data":{
"id":"5863f7136ef9da255ad9a9bc",
"type":"component"
},
"links":{
"self":"/v2/components/5863f7136ef9da255ad9a9bc"
}
},
"user":{
"data":{
"id":"585d389b90ea62ce348a478b",
"type":"user"
},
"links":{
"self":"/v2/users/585d389b90ea62ce348a478b"
}
}
},
"attributes":{
"method":"hello123",
"result":{
"foo":"bar1",
"baz":"qwe1"
}
}
},
"meta":{}
}
Authorization
A member of a Workspace can get any sample from own Workspace.
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 \
-X POST \
-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"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"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"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
},
"component":{
"data":{
"id":"5863f7136ef9da255ad9a9bc",
"type":"component"
},
"links":{
"self":"/v2/components/5863f7136ef9da255ad9a9bc"
}
},
"user":{
"data":{
"id":"585d389b90ea62ce348a478b",
"type":"user"
},
"links":{
"self":"/v2/users/585d389b90ea62ce348a478b"
}
}
},
"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. |
| relationships.workspace.data.id | yes | An Id of the Wokspace |
| relationships.workspace.data.type | yes | A value must be workspace |
Authorization
A member of a Workspace with permission workspaces.flow.edit can create a sample in own Workspace.
Returns
Returns data sample object if the call succeeded.
Update data sample
Example Request:
curl https://api.elastic.io/v2/data-samples/{DATASAMPLE_ID} \
-X PATCH \
-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"
}
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"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"
}
},
"workspace":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
},
"component":{
"data":{
"id":"5863f7136ef9da255ad9a9bc",
"type":"component"
},
"links":{
"self":"/v2/components/5863f7136ef9da255ad9a9bc"
}
},
"user":{
"data":{
"id":"585d389b90ea62ce348a478b",
"type":"user"
},
"links":{
"self":"/v2/users/585d389b90ea62ce348a478b"
}
}
},
"attributes":{
"method":"hello123",
"result":{
"foo":"bar",
"baz":"foo"
}
}
},
"meta":{}
}
HTTP Request
PATCH https://api.elastic.io/v2/data-samples/{DATASAMPLE_ID}
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value must be data-sample |
| attributes.result | no | Data sample body |
Authorization
A member of a Workspace with permission workspaces.flow.edit can update a sample in own Workspace.
Returns
Returns updated data sample object if the call succeeded.
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:
selectModelallows retrieving available options for certain parameter of configuration, when component/module is used in some node in some flowgetMetaModelallows retrieving metadata for certain configuration of some node of some flowverifyCredentialsallows verifying if a configuration of credential of a certain component is valid
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:
- A method execution is scheduled by sending a request corresponding endpoint (see below). The API responds with
202 Accepted. The resource in theLocationHTTP header is the URL to poll for execution results. - The execution result is polled periodically by sending requests to the polling resource
exec/poll/{EXECUTION_ID}. The API responds with200 OKif the result is not available yet. Please see how to poll execution results. - Once the result is available the polling resource responds with
303 See Other. The resource in theLocationHTTP header is the URL to get the results of the execution. Please see how to poll execution results. - The results are retrieved from
exec/result/{EXECUTION_ID}. Please see how to retrieve execution results.
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":{
"fields":{
"apiKey":"elasticio"
}
},
"relationships":{
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
}
}
}
}
}'
Example Response:
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: 'https://api.elastic.io/v2/exec/poll/58becb8259a65f18c5c60eb0'
{
"data":{
"id":"5aaf90a2d0516d00077556cf",
"type":"execution-result",
"links":{
"self":"/v2/exec/result/5aaf90a2d0516d00077556cf"
},
"attributes":{
"result":{
},
"status":"Pending request, waiting other process"
}
},
"meta":{}
}
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
This request is authorized for the users with the workspaces.credential.edit permission. 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 verify-credential. |
| attributes.fields | Yes | An object which represents the configuration of credential. The semantics are same as in creating a credential. |
| relationships.workspace.data.id | Yes | ID of the Workspace |
| relationships.workspace.data.type | Yes | Value must be workspace |
| relationships.agent.data.id | No | ID of the agent |
| relationships.agent.data.type | No | In case, agent specified, this must be agent |
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":{
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
}
},
"credential":{
"data":{
"id":"{CREDENTIAL_ID}",
"type":"credential"
}
}
}
}
}'
Example Response:
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: 'https://api.elastic.io/v2/exec/poll/58becb8359a65f18c5c60ec4'
{
"data":{
"id":"5aaf9d5bd0516d000775621c",
"type":"execution-result",
"links":{
"self":"/v2/exec/result/5aaf9d5bd0516d000775621c"
},
"attributes":{
"result":{},
"status":"Pending request, waiting other process"
}
},
"meta":{}
}
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
This request is authorized for the users with the workspaces.flow.edit permission. 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.workspace.data.id | Yes | ID of the Workspace |
| relationships.workspace.data.type | Yes | Value must be workspace |
| relationships.credential.data.id | No | If credentials are specified in the component’s descriptor, create a credential first and use its id. |
| relationships.credential.data.type | No | If credentials are specified in the component’s descriptor, value credential must be used here. |
| relationships.agent.data.id | No | ID of the agent |
| relationships.agent.data.type | No | In case, agent specified, this must be agent |
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":"select-model",
"attributes":{
"module":"{MODULE}",
"method":"{METHOD}",
"fields":{
"some_field":"value",
"another_field":"another_value"
}
},
"relationships":{
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
}
},
"credential":{
"data":{
"id":"{CREDENTIAL_ID}",
"type":"credential"
}
}
}
}
}'
Example Response:
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: 'https://api.elastic.io/v2/exec/poll/58becb8059a65f18c5c60e41'
{
"data":{
"id":"5aafb9e1d0516d0007757b71",
"type":"execution-result",
"links":{
"self":"/v2/exec/result/5aafb9e1d0516d0007757b71"
},
"attributes":{
"result":{},
"status":"Pending request, waiting other process"
}
},
"meta":{}
}
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
This request is authorized for the users with the workspaces.flow.edit permission. 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.method | Yes | Name of the method, which returns select model data. |
| attributes.fields | Yes | Contains values for component’s fields. Semantics are same as defining fields for a node in a flow graph. |
| relationships.workspace.data.id | Yes | ID of the Workspace |
| relationships.workspace.data.type | Yes | Value must be workspace |
| relationships.credential.data.id | No | If credentials are specified in the component’s descriptor, create a credential first and use its id. |
| relationships.credential.data.type | No | If credentials are specified in the component’s descriptor, value credential must be used here. |
| relationships.agent.data.id | No | ID of the agent |
| relationships.agent.data.type | No | In case, agent specified, this must be agent |
Poll a result of an execution
Example Request:
curl https://api.elastic.io/v2/exec/poll/{EXECUTION_ID} \
-u {EMAIL}:{APIKEY}
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: /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 |
|---|---|---|
| EXECUTION_ID | yes | Execution identifier. |
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}
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5aafcd56d0516d0007758cff",
"type":"execution-result",
"links":{
"self":"/v2/exec/result/5aafcd56d0516d0007758cff"
},
"attributes":{
"result":{
"data":{
"some_field_of_result":"value",
"another_field":"another_value"
}
}
}
},
"meta":{}
}
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.
Flows
Retrieve all flows
Example Request (with custom paging):
curl 'https://api.elastic.io/v2/flows?workspace_id=59d341e9037f7200184a408b&page[size]=20&page[number]=1' \
-g -u {EMAIL}:{APIKEY}
Example Request (with filter):
curl 'https://api.elastic.io/v2/flows?workspace_id=59d341e9037f7200184a408b&filter[status]=active' \
-g -u {EMAIL}:{APIKEY}
Example Request (with search):
curl 'https://api.elastic.io/v2/flows?workspace_id=59d341e9037f7200184a408b&search=webhook' \
-g -u {EMAIL}:{APIKEY}
Example Request (with custom sorting):
curl 'https://api.elastic.io/v2/flows?workspace_id=59d341e9037f7200184a408b&sort=-updated_at' \
-g -u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"type":"flow",
"id":"585918da586224001b96de89",
"links":{
"self":"/v2/flows/585918da586224001b96de89"
},
"attributes":{
"name":"Timer to E-Mail Test",
"status":"inactive",
"type":"ordinary",
"created_at":"2018-03-27T15:39:02.825Z",
"current_status":"inactive",
"default_mapper_type":"jsonata",
"description":"",
"updated_at":"2018-03-27T15:39:02.923Z",
"graph":{
"nodes":[
{
"id":"step_1",
"component_id": "55ba18e35d04040500000004",
"command":"elasticio/timer:timer",
"name":"",
"description":"",
"fields":{
"interval":"minute"
}
},
{
"id":"step_2",
"component_id": "593809a16b1d1f00196b74cd",
"command":"elasticio/email:send",
"name":"",
"description":""
}
],
"edges":[
{
"id":"mapper:step_1:step_2",
"config":{
"mapper_type":"jsonata",
"condition":null,
"mapper":{
"to":"\"test@example.com\"",
"subject":"\"StrongMapper\"",
"textBody":"Address.Street"
}
},
"source":"step_1",
"target":"step_2"
}
]
}
},
"relationships":{
"user":{
"data":{
"type":"user",
"id":"560e5a27734d480a00000002"
},
"links":{
"self":"/v2/users/560e5a27734d480a00000002"
}
},
"workspace":{
"data":{
"type":"workspace",
"id":"573dd76962436c349f000003"
},
"links":{
"self":"/v2/workspaces/573dd76962436c349f000003"
}
},
"versions":{
"links":{
"related":"/v2/flows/585918da586224001b96de89/versions"
}
},
"latest_version":{
"data":{
"id":"787513ee82625ef46bc10372cb6485a535b54c5f",
"type":"flow-version"
},
"links":{
"self":"/v2/flows/585918da586224001b96de89/versions/787513ee82625ef46bc10372cb6485a535b54c5f",
"related":"/v2/flows/585918da586224001b96de89/versions/787513ee82625ef46bc10372cb6485a535b54c5f"
}
}
}
}
],
"meta":{
"page":1,
"per_page":10,
"total":2,
"total_pages":1
},
"links":{
"self":"/v2/flows"
}
}
This resource allows you to retrieve flows.
HTTP Request
GET https://api.elastic.io/v2/flows/
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| workspace_id | yes | An Id of the Workspace |
| page[size] | no | Amount of items per page. Default is 50. |
| page[number] | no | Number of page you want to display. Default is 1. |
| filter[has_draft] | no | Filter flows only with or without a draft. May be true or false. |
| filter[status] | no | Filter by status. May be any of: active, inactive. |
| filter[type] | no | Filter by flow type. May be any of: ordinary, long_running. |
| filter[user] | no | Filter by user. Must be id of User who created the flow. User could be found in relationships of the flow. |
| sort | no | Sort flows list by certain field. May be created_at, updated_at or name. Prefix field name with - for reversed (desc) order e.g. sort=-updated_at. Default sort is by id. |
| search | no | Search flows by a word or a phrase contained in a description OR in a name. Behavior is similar to operator LIKE in SQL. Case insensitive. Leading/following spaces are trimmed. |
Returns
Returns all flows in the specified Workspace.
Retrieve a flow by ID
Example Request:
curl https://api.elastic.io/v2/flows/{FLOW_ID} \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"type":"flow",
"id":"585918da586224001b96de89",
"links":{
"self":"/v2/flows/585918da586224001b96de89"
},
"attributes":{
"name":"Timer to E-Mail Test",
"status":"inactive",
"type":"ordinary",
"created_at":"2018-03-27T15:39:02.825Z",
"current_status":"inactive",
"default_mapper_type":"jsonata",
"description":"",
"updated_at":"2018-03-27T15:39:02.923Z",
"graph":{
"nodes":[
{
"id":"step_1",
"component_id": "55ba18e35d04040500000004",
"command":"elasticio/timer:timer",
"name":"",
"description":"",
"fields":{
"interval":"minute"
}
},
{
"id":"step_2",
"component_id": "593809a16b1d1f00196b74cd",
"command":"elasticio/email:send",
"name":"",
"description":""
}
],
"edges":[
{
"id":"mapper:step_1:step_2",
"config":{
"mapper_type":"jsonata",
"condition":null,
"mapper":{
"to":"\"test@example.com\"",
"subject":"\"StrongMapper\"",
"textBody":"Address.Street"
}
},
"source":"step_1",
"target":"step_2"
}
]
}
},
"relationships":{
"user":{
"data":{
"type":"user",
"id":"560e5a27734d480a00000002"
},
"links":{
"self":"/v2/users/560e5a27734d480a00000002"
}
},
"workspace":{
"data":{
"type":"workspace",
"id":"573dd76962436c349f000003"
},
"links":{
"self":"/v2/workspaces/573dd76962436c349f000003"
}
},
"versions":{
"links":{
"related":"/v2/flows/585918da586224001b96de89/versions"
}
},
"latest_version":{
"data":{
"id":"787513ee82625ef46bc10372cb6485a535b54c5f",
"type":"flow-version"
},
"links":{
"self":"/v2/flows/585918da586224001b96de89/versions/787513ee82625ef46bc10372cb6485a535b54c5f",
"related":"/v2/flows/585918da586224001b96de89/versions/787513ee82625ef46bc10372cb6485a535b54c5f"
}
}
}
},
"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 Workspace, 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 -X POST https://api.elastic.io/v2/flows \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data":{
"attributes":{
"default_mapper_type":"jsonata",
"type":"ordinary",
"name":"My flow",
"description":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"cron":null,
"graph":{
"nodes":[
{
"name":"",
"description":"",
"command":"elasticio/simple-trigger-component:timer@latest",
"fields":{
},
"id":"step_1",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
},
{
"name":"My component",
"description":"Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.",
"command":"elasticio/code:execute@latest",
"fields":{
"code":"{{Put your custom Node.js code here}}"
},
"id":"step_2",
"agent_id":"{AGENT_ID}",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
},
{
"name":"",
"description":"",
"command":"help/petstore:createPetWithPromise@latest",
"fields":{
},
"id":"step_3",
"credentials_id":"{CREDENTIAL_ID}",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
},
{
"name":"",
"description":"",
"command":"help/petstore:createPetWithPromise@latest",
"fields":{
},
"id":"step_4",
"credentials_id":"{CREDENTIAL_ID}",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
}
],
"edges":[
{
"config":{
"mapper":{
},
"condition":null
},
"source":"step_1",
"target":"step_2"
},
{
"config":{
"mapper_type":"jsonata",
"mapper":{
"status":"\"sold\"",
"name":"result"
},
"condition":null
},
"source":"step_2",
"target":"step_3"
},
{
"config":{
"mapper_type":"jsonata",
"mapper":{
"status":"\"pending\"",
"name":"result"
},
"condition":null
},
"source":"step_2",
"target":"step_4"
}
]
}
},
"relationships":{
"workspace":{
"data":{
"type":"workspace",
"id":"{WORKSPACE_ID}"
}
}
},
"type":"flow"
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"{FLOW_ID}",
"type":"flow",
"links":{
"self":"/v2/flows/{FLOW_ID}"
},
"attributes":{
"api_version":"2.0",
"created_at":"2019-06-27T14:28:17.918Z",
"current_status":"inactive",
"default_mapper_type":"jsonata",
"description":"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
"graph":{
"nodes":[
{
"id":"step_1",
"component_id":"{COMPONENT_ID}",
"command":"elasticio/simple-trigger-component:timer@latest",
"name":"",
"description":"",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
},
{
"id":"step_2",
"component_id":"{COMPONENT_ID}",
"command":"elasticio/code:execute@latest",
"name":"My component",
"description":"Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.",
"agent_id":"{AGENT_ID}",
"fields":{
"code":"// Please note only Node.js code is supported here\nasync function run(msg) {\n\tconsole.log('Incoming message is %s', JSON.stringify(msg));\n\tconst body = { result : 'Hello world!' };\n\t// You can emit as many data messages as required\n\tawait this.emit('data', { body });\n\tconsole.log('Execution finished');\n}"
},
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
},
{
"id":"step_3",
"component_id":"{COMPONENT_ID}",
"command":"help/petstore:createPetWithPromise@latest",
"name":"",
"description":"",
"credentials_id":"{CREDENTIAL_ID}",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
},
{
"id":"step_4",
"component_id":"{COMPONENT_ID}",
"command":"help/petstore:createPetWithPromise@latest",
"name":"",
"description":"",
"credentials_id":"{CREDENTIAL_ID}",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
}
],
"edges":[
{
"id":"step_1:step_2",
"source":"step_1",
"target":"step_2"
},
{
"id":"mapper:step_2:step_3",
"config":{
"mapper_type":"jsonata",
"mapper":{
"status":"\"sold\"",
"name":"result"
},
"condition":null
},
"source":"step_2",
"target":"step_3"
},
{
"id":"mapper:step_2:step_4",
"config":{
"mapper_type":"jsonata",
"mapper":{
"status":"\"pending\"",
"name":"result"
},
"condition":null
},
"source":"step_2",
"target":"step_4"
}
]
},
"last_modified":"2019-06-27T14:28:17.940Z",
"name":"My flow",
"status":"inactive",
"type":"ordinary",
"updated_at":"2019-06-27T14:28:17.940Z"
},
"relationships":{
"user":{
"data":{
"id":"{USER_ID}",
"type":"user"
},
"links":{
"self":"/v2/users/{USER_ID}"
}
},
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
},
"links":{
"self":"/v2/workspaces/{WORKSPACE_ID}"
}
},
"versions":{
"links":{
"related":"/v2/flows/{FLOW_ID}/versions"
}
},
"latest_version":{
"data":{
"id":"{FLOW_VERSION_ID}",
"type":"flow-version"
},
"links":{
"self":"/v2/flows/{FLOW_ID}/versions/{FLOW_VERSION_ID}",
"related":"/v2/flows/{FLOW_ID}/versions/{FLOW_VERSION_ID}"
}
}
}
},
"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 |
| attributes.default_mapper_type | yes | The mapper type. A value must be jsonata (The handlebars is now deprecated) |
| relationships.workspace.data.id | yes | An Id of the Workspace |
| relationships.workspace.data.type | yes | A value must be workspace |
Authorization
This request is authorized for a user with the workspaces.flow.edit permission.
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"
}
}
}'
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"type":"flow",
"id":"585918da586224001b96de89",
"links":{
"self":"/v2/flows/585918da586224001b96de89"
},
"attributes":{
"name":"this is a test task",
"status":"inactive",
"type":"ordinary",
"created_at":"2018-03-27T15:39:02.825Z",
"current_status":"inactive",
"default_mapper_type":"jsonata",
"description":null,
"updated_at":"2018-03-27T15:39:02.923Z",
"graph":{
"nodes":[
{
"id":"step_1",
"component_id": "55ba18e35d04040500000004",
"command":"elasticio/timer:timer",
"name":"",
"description":"",
"fields":{
"interval":"minute"
}
},
{
"id":"step_2",
"component_id": "593809a16b1d1f00196b74cd",
"command":"elasticio/email:send",
"name":"",
"description":""
}
],
"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"
}
},
"workspace":{
"data":{
"type":"workspace",
"id":"573dd76962436c349f000003"
},
"links":{
"self":"/v2/workspaces/573dd76962436c349f000003"
}
},
"versions":{
"links":{
"related":"/v2/flows/585918da586224001b96de89/versions"
}
},
"latest_version":{
"data":{
"id":"787513ee82625ef46bc10372cb6485a535b54c5f",
"type":"flow-version"
},
"links":{
"self":"/v2/flows/585918da586224001b96de89/versions/787513ee82625ef46bc10372cb6485a535b54c5f",
"related":"/v2/flows/585918da586224001b96de89/versions/787513ee82625ef46bc10372cb6485a535b54c5f"
}
}
}
},
"meta":{}
}
This resource allows you to update the given flow. A new version of the flow will be created. The new version becomes the latest version of the 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 |
Authorization
This request is authorized for a user with the workspaces.flow.edit permission.
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'
Example response
HTTP/1.1 202 Accepted
{
"data":{},
"meta":{}
}
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 |
Authorization
This request is authorized for a user with the workspaces.flow.toggleStatus permission.
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'
Example response
HTTP/1.1 202 Accepted
{
"data":{},
"meta":{}
}
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 |
Authorization
This request is authorized for a user with the workspaces.flow.toggleStatus permission.
Returns
Empty response
Delete a flow
Example Request:
curl https://api.elastic.io/v2/flows/{FLOW_ID} \
-X DELETE \
-u {EMAIL}:{APIKEY}
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
Flow drafts
Retrieve a flow draft
Example Request:
curl https://api.elastic.io/v2/flows/{FLOW_ID}/draft \
-X GET \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5abe0cabaa56a1749856226b",
"type":"flow-draft",
"links":{
"self":"/v2/flows/5abbb9d4bc984b000739761a/draft"
},
"attributes":{
"name":"2803ANode.js Code to E-Mail",
"description":null,
"cron":null,
"graph":{
"nodes":[
{
"id":"step_1",
"command":"elasticio/timer:timer@latest",
"name":"",
"description":"",
"agent_id":"5a09deda2d5f49665afb739a",
"fields":{
"interval":"minute"
}
},
{
"id":"step_2",
"command":"elasticio/email:send@latest",
"name":"",
"description":"",
"agent_id":"5a09deda2d5f49665afb739a"
},
{
"id":"step_3",
"command":"elasticio/code:execute@latest",
"name":"",
"description":"",
"agent_id":"5a09deda2d5f49665afb739a",
"fields":{
"code":"//Your NodeJS code"
}
}
],
"edges":[
{
"id":"step_1:step_3",
"source":"step_1",
"target":"step_3"
},
{
"id":"mapper:step_3:step_2",
"config":{
"mapper_type":"jsonata",
"condition":null,
"mapper":{
"textBody":"message",
"subject":"\"2803_SW)RT\"",
"to":"\"test@example.com\""
}
},
"source":"step_3",
"target":"step_2"
}
]
},
"created_at":"2018-03-30T10:08:43.582Z",
"updated_at":"2018-03-30T10:08:43.582Z"
},
"relationships":{
"user":{
"data":{
"id":"59d3562c68ed850019bde27f",
"type":"user"
},
"links":{
"self":"/v2/users/59d3562c68ed850019bde27f"
}
},
"flow":{
"data":{
"id":"5abbb9d4bc984b000739761a",
"type":"flow"
},
"links":{
"self":"/v2/flows/5abbb9d4bc984b000739761a"
}
}
}
},
"meta":{}
}
This resource allows you to get a flow draft.
HTTP Request
GET https://api.elastic.io/v2/flows/{FLOW_ID}/draft
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| FLOW_ID | yes | Flow ID |
Returns
Returns a flow draft
Create/update a flow draft
Example Request:
curl https://api.elastic.io/v2/flows/{FLOW_ID}/draft \
-X PUT \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "flow-draft",
"attributes": {
"name": "Timer to E-Mail",
"description": "Some real description",
"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}}"
}
}
}
]
}
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5abe0cabaa56a1749856226b",
"type":"flow-draft",
"links":{
"self":"/v2/flows/5abbb9d4bc984b000739761a/draft"
},
"attributes":{
"name":"2803ANode.js Code to E-Mail",
"description":null,
"cron":null,
"graph":{
"nodes":[
{
"id":"step_1",
"command":"elasticio/timer:timer@latest",
"name":"",
"description":"",
"agent_id":"5a09deda2d5f49665afb739a",
"fields":{
"interval":"minute"
}
},
{
"id":"step_2",
"command":"elasticio/email:send@latest",
"name":"",
"description":"",
"agent_id":"5a09deda2d5f49665afb739a"
},
{
"id":"step_3",
"command":"elasticio/code:execute@latest",
"name":"",
"description":"",
"agent_id":"5a09deda2d5f49665afb739a",
"fields":{
"code":"//Your NodeJS code"
}
}
],
"edges":[
{
"id":"step_1:step_3",
"source":"step_1",
"target":"step_3"
},
{
"id":"mapper:step_3:step_2",
"config":{
"mapper_type":"jsonata",
"condition":null,
"mapper":{
"textBody":"message",
"subject":"\"2803_SW)RT\"",
"to":"\"test@example.com\""
}
},
"source":"step_3",
"target":"step_2"
}
]
},
"created_at":"2018-03-30T10:08:43.582Z",
"updated_at":"2018-03-30T10:08:43.582Z"
},
"relationships":{
"user":{
"data":{
"id":"59d3562c68ed850019bde27f",
"type":"user"
},
"links":{
"self":"/v2/users/59d3562c68ed850019bde27f"
}
},
"flow":{
"data":{
"id":"5abbb9d4bc984b000739761a",
"type":"flow"
},
"links":{
"self":"/v2/flows/5abbb9d4bc984b000739761a"
}
}
}
},
"meta":{}
}
This resource allows you to create/update a flow draft.
HTTP Request
PUT https://api.elastic.io/v2/flows/{FLOW_ID}/draft
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| FLOW_ID | yes | Flow ID |
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value must be flow-draft |
| attributes.name | no | Flow name |
| attributes.description | no | Flow description |
| attributes.graph | no | Flow graph representing component connections |
| attributes.cron | no | Cron expression |
Returns
Returns the created/updated flow draft
Delete a flow draft
Example Request:
curl https://api.elastic.io/v2/flows/{FLOW_ID}/draft \
-X DELETE \
-u {EMAIL}:{APIKEY}
This resource allows you to delete a flow draft.
HTTP Request
DELETE https://api.elastic.io/v2/flows/{FLOW_ID}/draft
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| FLOW_ID | yes | Flow ID |
Example Response:
HTTP/1.1 204 No Content
Flow versions
Retrieve all flow versions
Example Request:
curl https://api.elastic.io/v2/flows/{FLOW_ID}/versions?page[size]=20&page[number]=1 \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"af65130306caf1c421708a1cfe7edcb56900a6af",
"type":"flow-version",
"links":{
"self":"/v2/flows/5ab0eeabbd6d6400079b4628/versions/af65130306caf1c421708a1cfe7edcb56900a6af"
},
"attributes":{
"name":"Node.js Code to Node.js Code draft 2",
"description":null,
"graph":{
"nodes":[
{
"id":"step_1",
"command":"elasticio/code:executeTrigger@latest",
"name":"",
"description":"",
"fields":{
"code":"//Your NodeJS code"
}
},
{
"id":"step_2",
"command":"elasticio/code:execute@latest",
"name":"",
"description":"",
"fields":{
"code":"// Your NodeJS code"
}
},
{
"id":"step_3",
"command":"elasticio/code:execute@latest",
"name":"",
"description":"",
"fields":{
"code":"// Your NodeJS code"
}
}
],
"edges":[
{
"id":"step_1:step_2",
"source":"step_1",
"target":"step_2"
},
{
"id":"step_1:step_3",
"source":"step_1",
"target":"step_3"
}
]
},
"created_at":"2018-03-20T14:12:54.361Z"
},
"relationships":{
"user":{
"data":{
"id":"59d22e7eeb865b0018adc248",
"type":"user"
},
"links":{
"self":"/v2/users/59d22e7eeb865b0018adc248"
}
},
"flow":{
"data":{
"id":"5ab0eeabbd6d6400079b4628",
"type":"flow"
},
"links":{
"self":"/v2/flows/5ab0eeabbd6d6400079b4628"
}
}
}
}
],
"meta":{
"page":1,
"per_page":50,
"total":1,
"total_pages":1
}
}
These versions represent the history of changes of the flow and are sorted chronologically by created_at.
Each version has an id and represents a flow’s state at the given created_at time.
It also exposes a relationship to the author of the change.
HTTP Request
GET https://api.elastic.io/v2/flows/{FLOW_ID}/versions
URL Parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
| FLOW_ID | Yes | Flow identifier | |
| page[size] | No | Amount of items per page | 50 |
| page[number] | No | Number of page you want to display | 1 |
Returns
The list of versions for the specified flow.
Retrieve flow version by hash
Example Request:
curl https://api.elastic.io/v2/flows/{FLOW_ID}/versions/{VERSION_HASH} \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"af65130306caf1c421708a1cfe7edcb56900a6af",
"type":"flow-version",
"links":{
"self":"/v2/flows/5ab0eeabbd6d6400079b4628/versions/af65130306caf1c421708a1cfe7edcb56900a6af"
},
"attributes":{
"name":"Node.js Code to Node.js Code draft 2",
"description":null,
"graph":{
"nodes":[
{
"id":"step_1",
"command":"elasticio/code:executeTrigger@latest",
"name":"",
"description":"",
"fields":{
"code":"//Your NodeJS code"
}
},
{
"id":"step_2",
"command":"elasticio/code:execute@latest",
"name":"",
"description":"",
"fields":{
"code":"// Your NodeJS code"
}
},
{
"id":"step_3",
"command":"elasticio/code:execute@latest",
"name":"",
"description":"",
"fields":{
"code":"// Your NodeJS code"
}
}
],
"edges":[
{
"id":"step_1:step_2",
"source":"step_1",
"target":"step_2"
},
{
"id":"step_1:step_3",
"source":"step_1",
"target":"step_3"
}
]
},
"created_at":"2018-03-20T14:12:54.361Z"
},
"relationships":{
"user":{
"data":{
"id":"59d22e7eeb865b0018adc248",
"type":"user"
},
"links":{
"self":"/v2/users/59d22e7eeb865b0018adc248"
}
},
"flow":{
"data":{
"id":"5ab0eeabbd6d6400079b4628",
"type":"flow"
},
"links":{
"self":"/v2/flows/5ab0eeabbd6d6400079b4628"
}
}
}
},
"meta":{}
}
This resource allows to you retrieve specific version of the flow by its version hash.
HTTP Request
GET https://api.elastic.io/v2/flows/{FLOW_ID}/versions/{VERSION_HASH}
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| FLOW_ID | Yes | Flow identifier |
| VERSION_HASH | Yes | Version hash |
Returns
Specific version of the flow.
Resources
Storage: Create a signed url
Example Request:
curl https://api.elastic.io/v2/resources/storage/signed-url \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"put_url":"https://steward_host/files/1ksksiao",
"get_url":"https://steward_host/files/34rwer34",
"expires":18000
}
This endpoint creates a new signed url in Storage
HTTP Request
POST https://api.elastic.io/v2/resources/storage/signed-url
Returns
Returns an HTTP 200 in case of successful url creation
SSH keys
Retrieve all SSH keys
Example Request:
curl https://api.elastic.io/v2/sshkeys/ \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"5a4f59dbcbe7940019697ec5",
"type":"sshkey",
"links":{
"self":"/v2/sshkeys/5a4f59dbcbe7940019697ec5"
},
"attributes":{
"key":"ssh-key",
"title":"test@example-UX430UQ",
"fingerprint":"fd:d4:98:92:ed:d7:3a:0c:a2:42:ff:78:57:15:88:fa"
},
"relationships":{
"user":{
"data":{
"id":"59d22e7eeb865b0018adc248",
"type":"user"
},
"links":{
"self":"/v2/users/59d22e7eeb865b0018adc248"
}
}
}
}
],
"meta":{},
"links":{
"self":"/v2/sshkeys"
}
}
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 '
{
"data": {
"type": "sshkey",
"attributes": {
"key": "ssh-rsa YOUR KEY GOES HERE",
"title": "My New Key"
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"5aabedf5bd6d6400079b45f1",
"type":"sshkey",
"links":{
"self":"/v2/sshkeys/5aabedf5bd6d6400079b45f1"
},
"attributes":{
"key":"ssh-key",
"title":"1603testAndDelMe",
"fingerprint":"3a:2b:8e:7c:dc:82:3e:de:54:f4:58:8a:7d:55:fb:15"
},
"relationships":{
"user":{
"data":{
"id":"59d22e7eeb865b0018adc248",
"type":"user"
},
"links":{
"self":"/v2/users/59d22e7eeb865b0018adc248"
}
}
}
},
"meta":{}
}
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}
Example Response:
HTTP/1.1 204 No Content
This resource allows you to delete your own 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?contract_id={CONTRACT_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"5aa7de77a0c086000785c53e",
"type":"team",
"links":{
"self":"/v2/teams/5aa7de77a0c086000785c53e"
},
"attributes":{
"name":"Team_name"
},
"relationships":{
"contract":{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"contract"
},
"links":{
"self":"/v2/contract/59d341e9037f7200184a408b"
}
},
"users":{
"data":[
{
"id":"5a816bebcad2b40007adcaf2",
"type":"user"
}
]
},
"components":{
"data":[
{
"id":"5a96906605f3f60007a76324",
"type":"component"
}
]
}
},
"meta":{},
"links":{
"self":"/v2/teams"
}
}
]
}
This resource allows retrieving all teams where the current user remains a member.
HTTP Request
GET https://api.elastic.io/v2/teams/
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| contract_id | yes | An Id of the Contract |
Returns
Returns teams metadata object if the call succeeded.
Retrieve team by ID
Example Request:
curl https://api.elastic.io/v2/teams/{TEAM_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": "5a660b0309949a000716d4db",
"type": "team",
"links": {
"self": "/v2/teams/5a660b0309949a000716d4db"
},
"attributes": {
"name": "2201team"
},
"relationships": {
"contract": {
"data": {
"id": "5b5ed1cf272cf80011ae7b43",
"type": "contract"
},
"links": {
"self": "/v2/contracts/5b5ed1cf272cf80011ae7b43"
}
},
"users": {
"data": [
{
"id": "59d22e7eeb865b0018adc248",
"type": "user"
},
{
"id": "560e5a27734d480a00000002",
"type": "user"
},
{
"id": "59d3562c68ed850019bde27f",
"type": "user"
}
]
},
"components": {
"data": [
{
"id": "5a81a065fcc9380007322e86",
"type": "component"
},
{
"id": "5a6713361231e7000772a9f2",
"type": "component"
}
]
}
}
},
"meta": {},
"links": {
"self": "/v2/teams/5a660b0309949a000716d4db"
}
}
This resource allows retrieving the team by ID where the current user remains a member.
HTTP Request
GET https://api.elastic.io/v2/teams/{TEAM_ID}
Returns
Returns team 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":"309myteam"
},
"relationships":{
"contract":{
"data":{
"id":"5b87c916bfeeb2441025c8bb",
"type":"contract"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"5aabe01bbd6d6400079b45c4",
"type":"team",
"links":{
"self":"/v2/teams/5aabe01bbd6d6433079b45c4"
},
"attributes":{
"name":"309myteam"
},
"relationships":{
"contract":{
"data":{
"id":"59d341e9037f72001833408b",
"type":"contract"
},
"links":{
"self":"/v2/contract/59d341e9037f7200133a408b"
}
},
"users":{
"data":[
{
"id":"59d22e7eeb86533018adc248",
"type":"user"
}
]
}
}
},
"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. |
| relationships.contract.data.id | yes | An Id of the contract |
| relationships.contract.data.type | yes | A value must be contract |
Authorization
This request is authorized to a user with the contracts.devTeam.edit permission.
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}"
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"59d3ace74a819c0018e9bb92",
"type":"team",
"links":{
"self":"/v2/teams/59d3ace74a819c0018e9bb92"
},
"attributes":{
"name":"Test_Team"
},
"relationships":{
"contract":{
"data":{
"id":"59d22e7eeb865b0018adc247",
"type":"contract"
},
"links":{
"self":"/v2/contract/59d22e7eeb865b0018adc247"
}
},
"users":{
"data":[
{
"id":"59d22e7eeb865b0018adc248",
"type":"user"
},
{
"id":"59f747c33f1d3c001901a44e",
"type":"user"
},
{
"id":"59d3562c68ed850019bde27f",
"type":"user"
}
]
}
}
},
"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 |
Authorization
This request is authorized to a user with the contracts.devTeam.edit permission.
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}"
}
}'
Example Response:
HTTP/1.1 204 No Content
Content-Type: application/json
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 |
Authorization
This request is authorized to a user with the contracts.devTeam.edit permission.
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}
Example Response:
HTTP/1.1 204 No Content
Content-Type: application/json
This resource allows you to delete a team. You cannot remove team which contains the repos, you should delete all repos first.
HTTP Request
DELETE https://api.elastic.io/v2/teams/{TEAM_ID}
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| TEAM_ID | yes | Team ID |
Authorization
This request is authorized to a user with the contracts.devTeam.edit permission.
Returns
Returns empty body
Tenants
What is a Tenant?
Tenant is a specific system’s environment virtual installation (a system’s clone, in other words) that allows customizing all the necessary parameters by sending a particular request to the API. Check the request examples below.
Create a Tenant
Example Request:
curl https://api.elastic.io/v2/tenants \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"tenant",
"attributes":{
"name":"My New Tenant",
"app_domain":"{{app_domain}}",
"api_domain":"{{api_domain}}",
"webhooks_domain":"{{webhooks_domain}}",
"git_receiver_host":"git_receiver_host",
"code":"{{css_code}}",
"header_logo_url":"//cdn.elastic.io/logo-mini.png",
"loading_logo_url":"//cdn.elastic.io/logo-mini.png",
"email_logo_url":"//cdn.elastic.io/logo-mini.png",
"favicon_url":"//cdn.elastic.io/logo-mini.png",
"terms_of_usage_url":"https://www.elastic.io/tou/",
"privacy_policy_url":"https://www.elastic.io/privacy-policy/",
"imprint_url":"https://www.elastic.io/legal-disclosure/",
"mailchimp_api_key":"{{mailchimp_api_key}}",
"mailchimp_list_id":"{{mailchimp_list_id}}",
"mandrill_email_from":"foo@foo.bar",
"mandrill_api_key":"{{mandrill_api_key}}",
"hide_register":false,
"is_default":false,
"hide_repos":false,
"hide_teams":false,
"hide_ssh_keys":false,
"hide_api_key":false,
"hide_docs":false,
"powered_by_elasticio":true,
"css_enabled":false,
"default_workspace_type":"limited",
"customStylesheets":[
{
"href":"http://path-to-1.css"
},
{
"href":"http://path-to-2.css"
}
],
"customScripts":[
{
"src":"http://path-to-1.js"
},
{
"src":"http://path-to-2.js"
}
],
"settings":{
"member_api_key":false
},
"custom_nav_menu_items":[
{
"title":"Catalogs",
"icon":"catalog-icon",
"custom_class":"custom_class",
"links":[
{
"url":"https://flow-catalog.example.com",
"title":"Flow catalog",
"icon":"flow-catalog-icon",
"custom_class":"custom_class"
},
{
"url":"https://components-catalog.example.com",
"title":"Components catalog",
"icon":"components-catalog-icon",
"custom_class":"custom_class"
}
]
},
{
"title":"Information",
"icon":"info",
"custom_class":"custom_class",
"links":[
{
"url":"https://docs.example.com",
"title":"Documentation",
"icon":"docs-icon",
"custom_class":"custom_class"
},
{
"url":"https://support.example.com",
"title":"Support",
"icon":"support-icon",
"custom_class":"custom_class"
},
{
"url":"https://video.example.com",
"title":"Video",
"icon":"video-icon",
"custom_class":"custom_class"
}
]
}
],
"html_meta":{
"description":"Lorem ipsum",
"author":"Acme Corporation",
"keywords":[
"foo",
"bar",
"baz"
]
}
}
}
}`
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"5c6e91b9d5b4b60012a796fe",
"type":"tenant",
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
},
"attributes":{
"name":"My New Tenant",
"app_domain":"{{app_domain}}",
"api_domain":"{{api_domain}}",
"webhooks_domain":"{{webhooks_domain}}",
"git_receiver_host":"git_receiver_host",
"css_enabled":false,
"code":"{{css_code}}",
"header_logo_url":"//cdn.elastic.io/logo-mini.png",
"loading_logo_url":"//cdn.elastic.io/logo-mini.png",
"email_logo_url":"//cdn.elastic.io/logo-mini.png",
"favicon_url":"//cdn.elastic.io/logo-mini.png",
"terms_of_usage_url":"https://www.elastic.io/tou/",
"privacy_policy_url":"https://www.elastic.io/privacy-policy/",
"imprint_url":"https://www.elastic.io/legal-disclosure/",
"mailchimp_list_id":"{{mailchimp_list_id}}",
"mandrill_email_from":"foo@foo.bar",
"hide_repos":false,
"hide_teams":false,
"hide_ssh_keys":false,
"hide_api_key":false,
"hide_docs":false,
"hide_register":false,
"powered_by_elasticio":true,
"default_workspace_type":"limited",
"ssl_certificates":{
},
"customStylesheets":[
{
"href":"http://path-to-1.css"
},
{
"href":"http://path-to-2.css"
}
],
"customScripts":[
{
"src":"http://path-to-1.js"
},
{
"src":"http://path-to-2.js"
}
],
"custom_nav_menu_items":[
{
"title":"Catalogs",
"icon":"catalog-icon",
"custom_class":"custom_class",
"links":[
{
"url":"https://flow-catalog.example.com",
"title":"Flow catalog",
"icon":"flow-catalog-icon",
"custom_class":"custom_class"
},
{
"url":"https://components-catalog.example.com",
"title":"Components catalog",
"icon":"components-catalog-icon",
"custom_class":"custom_class"
}
]
},
{
"title":"Information",
"icon":"info",
"custom_class":"custom_class",
"links":[
{
"url":"https://docs.example.com",
"title":"Documentation",
"icon":"docs-icon",
"custom_class":"custom_class"
},
{
"url":"https://support.example.com",
"title":"Support",
"icon":"support-icon",
"custom_class":"custom_class"
},
{
"url":"https://video.example.com",
"title":"Video",
"icon":"video-icon",
"custom_class":"custom_class"
}
]
}
],
"html_meta":{
"description":"Lorem ipsum",
"author":"Acme Corporation",
"keywords":[
"foo",
"bar",
"baz"
]
}
}
},
"meta":{},
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
}
}
This resource allows you to create a new Tenant.
HTTP Request
POST https://api.elastic.io/v2/tenants
Authorization
This request is authorized for the users with the tenants.tenant.create permission.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “tenant” |
| attributes.name | yes | Name of the Tenant |
| attributes.app_domain | yes | Name of the Tenant domain |
| attributes.code | yes | Tenant CSS-style |
| attributes.api_domain | no | Name of the Tenant API domain |
| attributes.webhooks_domain | no | Name of the Tenant webhooks domain |
| attributes.git_receiver_host | no | Name of the Tenant git receiver host |
| attributes.header_logo_url | no | The URL of image which will be displayed in the navigation panel (logo size 40x40 pixels, logo format - .png or .svg) |
| attributes.loading_logo_url | no | The URL of image which will be displayed during the page loading |
| attributes.email_logo_url | no | The URL of image which will be displayed in the emails |
| attributes.favicon_url | no | The URL of image which will be displayed as favicon |
| attributes.terms_of_usage_url | no | The URL which redirects to the terms of usage page |
| attributes.privacy_policy_url | no | The URL which redirects to the privacy policy page |
| attributes.imprint_url | no | The URL which redirects to the imprint page |
| attributes.mailchimp_api_key | no | The MailChimp API key |
| attributes.mailchimp_list_id | no | The MailChimp list id |
| attributes.mandrill_email_from | no | An email of the letters sender |
| attributes.mandrill_api_key | no | The mandrill API key |
| attributes.hide_register | no | A value should be true or false |
| attributes.is_default | no | A value should be true or false. You can set only one default tenant per installation |
| attributes.hide_repos | no | A value should be true or false |
| attributes.hide_teams | no | A value should be true or false |
| attributes.hide_ssh_keys | no | A value should be true or false |
| attributes.hide_api_key | no | A value should be true or false |
| attributes.hide_docs | no | A value should be true or false |
| attributes.powered_by_elasticio | no | A value should be true or false |
| attributes.css_enabled | no | A value should be true or false |
| attributes.settings.member_api_key | no | A value should be true or false |
| attributes.custom_nav_menu_items[].title | yes | The link text |
| attributes.custom_nav_menu_items[].icon | yes | The icon name from material-icons |
| attributes.custom_nav_menu_items[].custom_class | no | The class added to tag |
| attributes.custom_nav_menu_items[].links[].url | yes | The URL which redirects to the needed page |
| attributes.custom_nav_menu_items[].links[].title | yes | The link text |
| attributes.custom_nav_menu_items[].links[].icon | yes | The icon name from material-icons |
| attributes.custom_nav_menu_items[].links[].custom_class | no | The class added to tag |
| attributes.customStylesheets[] | no | Customer css stylesheets |
| attributes.customScripts[] | no | Customer js-scripts |
| attributes.default_workspace_type | no | Default Workspace type for Workspaces created in the Tenant. The value can be full or limited. If not specified, the attribute will be set to fullor limited depending on Tenant settings. |
| attributes.html_meta.description | no | Customer meta description in html pages |
| attributes.html_meta.author | no | Customer meta author in html pages |
| attributes.html_meta.keywords | no | Customer meta keywords in html pages |
Returns Tenant object if the call succeeded
Update a Tenant
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID} \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"tenant",
"attributes":{
"ssl_certificates":{
"app":"{{cert_id}}",
"api":"{{cert_id}}",
"webhooks":"{{cert_id}}"
},
"default_workspace_type":"full",
"custom_nav_menu_items":[
{
"title":"Catalogs",
"icon":"catalog-icon",
"custom_class":"custom_class",
"links":[
{
"url":"https://flow-catalog.example.com",
"title":"Flow catalog",
"icon":"flow-catalog-icon",
"custom_class":"custom_class"
},
{
"url":"https://components-catalog.example.com",
"title":"Components catalog",
"icon":"components-catalog-icon",
"custom_class":"custom_class"
}
]
},
{
"title":"Information",
"icon":"info",
"custom_class":"custom_class",
"links":[
{
"url":"https://docs.example.com",
"title":"Documentation",
"icon":"docs-icon",
"custom_class":"custom_class"
},
{
"url":"https://support.example.com",
"title":"Support",
"icon":"support-icon",
"custom_class":"custom_class"
},
{
"url":"https://video.example.com",
"title":"Video",
"icon":"video-icon",
"custom_class":"custom_class"
}
]
}
],
"customStylesheets":[
{
"href":"http://path-to-1.css"
},
{
"href":"http://path-to-2.css"
}
],
"customScripts":[
{
"src":"http://path-to-1.js"
},
{
"src":"http://path-to-2.js"
}
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c6e91b9d5b4b60012a796fe",
"type":"tenant",
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
},
"attributes":{
"name":"My New Tenant",
"app_domain":"{{app_domain}}",
"api_domain":"{{api_domain}}",
"webhooks_domain":"{{webhooks_domain}}",
"git_receiver_host":"git_receiver_host",
"css_enabled":false,
"code":"{{css_code}}",
"header_logo_url":"//cdn.elastic.io/logo-mini.png",
"loading_logo_url":"//cdn.elastic.io/logo-mini.png",
"email_logo_url":"//cdn.elastic.io/logo-mini.png",
"favicon_url":"//cdn.elastic.io/logo-mini.png",
"terms_of_usage_url":"https://www.elastic.io/tou/",
"privacy_policy_url":"https://www.elastic.io/privacy-policy/",
"imprint_url":"https://www.elastic.io/legal-disclosure/",
"mailchimp_list_id":"{{mailchimp_list_id}}",
"mandrill_email_from":"foo@foo.bar",
"hide_repos":false,
"hide_teams":false,
"hide_ssh_keys":false,
"hide_api_key":false,
"hide_docs":false,
"hide_register":false,
"powered_by_elasticio":true,
"default_workspace_type":"full",
"customStylesheets":[
{
"href":"http://path-to-1.css"
},
{
"href":"http://path-to-2.css"
}
],
"customScripts":[
{
"src":"http://path-to-1.js"
},
{
"src":"http://path-to-2.js"
}
],
"ssl_certificates":{
"app":"{{cert_id}}",
"api":"{{cert_id}}",
"webhooks":"{{cert_id}}"
},
"custom_nav_menu_items":[
{
"title":"Catalogs",
"icon":"catalog-icon",
"custom_class":"custom_class",
"links":[
{
"url":"https://flow-catalog.example.com",
"title":"Flow catalog",
"icon":"flow-catalog-icon",
"custom_class":"custom_class"
},
{
"url":"https://components-catalog.example.com",
"title":"Components catalog",
"icon":"components-catalog-icon",
"custom_class":"custom_class"
}
]
},
{
"title":"Information",
"icon":"info",
"custom_class":"custom_class",
"links":[
{
"url":"https://docs.example.com",
"title":"Documentation",
"icon":"docs-icon",
"custom_class":"custom_class"
},
{
"url":"https://support.example.com",
"title":"Support",
"icon":"support-icon",
"custom_class":"custom_class"
},
{
"url":"https://video.example.com",
"title":"Video",
"icon":"video-icon",
"custom_class":"custom_class"
}
]
}
],
"meta":{},
"links":{
"self":"/v2/tenants"
}
}
}
}
This resource allows you to update a given Tenant.
HTTP Request
PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}
Authorization
This request is authorized for the users with the tenants.tenant.edit permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| attributes.header_logo_url | no | The URL of image which will be displayed in the navigation panel (logo size 40x40 pixels, logo format - .png or .svg) |
| attributes.loading_logo_url | no | The URL of image which will be displayed during the page loading |
| attributes.email_logo_url | no | The URL of image which will be displayed in the emails |
| attributes.favicon_url | no | The URL of image which will be displayed as favicon |
| attributes.terms_of_usage_url | no | The URL which redirects to the terms of usage page |
| attributes.privacy_policy_url | no | The URL which redirects to the privacy policy page |
| attributes.imprint_url | no | The URL which redirects to the imprint page |
| attributes.mailchimp_api_key | no | The MailChimp API key |
| attributes.mailchimp_list_id | no | The MailChimp list id |
| attributes.mandrill_email_from | no | An email of the letters sender |
| attributes.mandrill_api_key | no | The mandrill API key |
| attributes.hide_register | no | A value should be true or false |
| attributes.is_default | no | A value should be true or false. You can set only one default tenant per installation |
| attributes.hide_repos | no | A value should be true or false |
| attributes.hide_teams | no | A value should be true or false |
| attributes.hide_ssh_keys | no | A value should be true or false |
| attributes.hide_api_key | no | A value should be true or false |
| attributes.hide_docs | no | A value should be true or false |
| attributes.powered_by_elasticio | no | A value should be true or false |
| attributes.css_enabled | no | A value should be true or false |
| attributes.settings.member_api_key | no | A value should be true or false |
| attributes.links | no | The value should be null as this attribute is not supported anymore. Please use the custom_nav_menu_items instead |
| attributes.custom_nav_menu_items[].title | yes | The link text |
| attributes.custom_nav_menu_items[].icon | yes | The icon name from material-icons |
| attributes.custom_nav_menu_items[].custom_class | no | The class added to tag |
| attributes.custom_nav_menu_items[].links[].url | yes | The URL which redirects to the needed page |
| attributes.custom_nav_menu_items[].links[].title | yes | The link text |
| attributes.custom_nav_menu_items[].links[].icon | yes | The icon name from material-icons |
| attributes.custom_nav_menu_items[].links[].custom_class | no | The class added to tag |
| attributes.ssl_certificates.app | no | An ID of SSL-certificate for a web-UI domain. |
| attributes.ssl_certificates.api | no | An ID of SSL-certificate for API domain. |
| attributes.ssl_certificates.webhooks | no | An ID of SSL-certificate for the webhooks domain. |
| attributes.customStylesheets[] | no | Customer css stylesheets. |
| attributes.customScripts[] | no | Customer js-scripts. |
| attributes.default_workspace_type | no | The type of Workspaces which will be created in given Tenant. The value must be full or limited |
Note: If Tenant’s domains are matches to the *.elastic.io (where * can not contain .) then given Tenants can use the default Certificates. To remove existed Certificates, specify them as null (e.g. "app": null)
Returns
Returns Tenant object if the call succeeded
Get Tenants
Example Request:
curl https://api.elastic.io/v2/tenants/
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"5c6e91b9d5b4b60012a796fe",
"type":"tenant",
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
},
"attributes":{
"name":"My New Tenant",
"app_domain":"{{app_domain}}",
"api_domain":"{{api_domain}}",
"webhooks_domain":"{{webhooks_domain}}",
"git_receiver_host":"git_receiver_host",
"css_enabled":false,
"code":"{{css_code}}",
"header_logo_url":"//cdn.elastic.io/logo-mini.png",
"loading_logo_url":"//cdn.elastic.io/logo-mini.png",
"email_logo_url":"//cdn.elastic.io/logo-mini.png",
"favicon_url":"//cdn.elastic.io/logo-mini.png",
"terms_of_usage_url":"https://www.elastic.io/tou/",
"privacy_policy_url":"https://www.elastic.io/privacy-policy/",
"imprint_url":"https://www.elastic.io/legal-disclosure/",
"mailchimp_list_id":"{{mailchimp_list_id}}",
"mandrill_email_from":"foo@foo.bar",
"hide_repos":false,
"hide_teams":false,
"hide_ssh_keys":false,
"hide_api_key":false,
"hide_docs":false,
"hide_register":false,
"powered_by_elasticio":true,
"ssl_certificates":{
},
"custom_nav_menu_items":[
{
"title":"Catalogs",
"icon":"catalog-icon",
"custom_class":"custom_class",
"links":[
{
"url":"https://flow-catalog.example.com",
"title":"Flow catalog",
"icon":"flow-catalog-icon",
"custom_class":"custom_class"
},
{
"url":"https://components-catalog.example.com",
"title":"Components catalog",
"icon":"components-catalog-icon",
"custom_class":"custom_class"
}
]
},
{
"title":"Information",
"icon":"info",
"custom_class":"custom_class",
"links":[
{
"url":"https://docs.example.com",
"title":"Documentation",
"icon":"docs-icon",
"custom_class":"custom_class"
},
{
"url":"https://support.example.com",
"title":"Support",
"icon":"support-icon",
"custom_class":"custom_class"
},
{
"url":"https://video.example.com",
"title":"Video",
"icon":"video-icon",
"custom_class":"custom_class"
}
]
}
],
"meta":{},
"links":{
"self":"/v2/tenants"
}
}
}
]
}
This resource allows you to retrieve all Tenants of the current user.
HTTP Request
GET https://api.elastic.io/v2/tenants/
Authorization
This request is authorized for the users with the tenants.tenant.get permission.
Get Tenant by Id
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c6e91b9d5b4b60012a796fe",
"type":"tenant",
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
},
"attributes":{
"name":"My New Tenant",
"app_domain":"{{app_domain}}",
"api_domain":"{{api_domain}}",
"webhooks_domain":"{{webhooks_domain}}",
"git_receiver_host":"git_receiver_host",
"css_enabled":false,
"code":"{{css_code}}",
"header_logo_url":"//cdn.elastic.io/logo-mini.png",
"loading_logo_url":"//cdn.elastic.io/logo-mini.png",
"email_logo_url":"//cdn.elastic.io/logo-mini.png",
"favicon_url":"//cdn.elastic.io/logo-mini.png",
"terms_of_usage_url":"https://www.elastic.io/tou/",
"privacy_policy_url":"https://www.elastic.io/privacy-policy/",
"imprint_url":"https://www.elastic.io/legal-disclosure/",
"mailchimp_list_id":"{{mailchimp_list_id}}",
"mandrill_email_from":"foo@foo.bar",
"hide_repos":false,
"hide_teams":false,
"hide_ssh_keys":false,
"hide_api_key":false,
"hide_docs":false,
"hide_register":false,
"powered_by_elasticio":true,
"ssl_certificates":{
},
"custom_nav_menu_items":[
{
"title":"Catalogs",
"icon":"catalog-icon",
"custom_class":"custom_class",
"links":[
{
"url":"https://flow-catalog.example.com",
"title":"Flow catalog",
"icon":"flow-catalog-icon",
"custom_class":"custom_class"
},
{
"url":"https://components-catalog.example.com",
"title":"Components catalog",
"icon":"components-catalog-icon",
"custom_class":"custom_class"
}
]
},
{
"title":"Information",
"icon":"info",
"custom_class":"custom_class",
"links":[
{
"url":"https://docs.example.com",
"title":"Documentation",
"icon":"docs-icon",
"custom_class":"custom_class"
},
{
"url":"https://support.example.com",
"title":"Support",
"icon":"support-icon",
"custom_class":"custom_class"
},
{
"url":"https://video.example.com",
"title":"Video",
"icon":"video-icon",
"custom_class":"custom_class"
}
]
}
]
}
},
"meta":{},
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
}
}
This resource allows you to retrieve a Tenant with the given ID.
HTTP Request
GET https://api.elastic.io/v2/tenants/{TENANT_ID}/
Authorization
This request is authorized for the users with the tenants.tenant.get permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
Delete Tenant
Example Request:
curl -i https://api.elastic.io/v2/tenants/{TENANT_ID} \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
This resource allows you to delete a Tenant with the given ID along with everything it includes.
A Tenant will be deleted only if it does not contain any contracts
HTTP Request
DELETE https://api.elastic.io/v2/tenants/{TENANT_ID} \
Authorization
This request is authorized for the users with the tenants.tenant.delete permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
Returns
Responds with the 204 No content message if the call succeeded (with empty body).
Get Tenant’s roles
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/roles
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{TENANT-POLICY_ID}",
"type":"tenant-policy",
"attributes":{
"roles":[
{
"i18n":{
"en":"Admin"
},
"role":"admin",
"permissions":[
"contracts.membership.edit",
"contracts.workspace.create",
"contracts.workspace.listAll",
"contracts.workspace.delete",
"contracts.repository.edit",
"contracts.devTeam.edit"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Member"
},
"role":"member",
"permissions":[
"contracts.workspace.create"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Admin"
},
"role":"admin",
"permissions":[
"workspaces.workspace.edit",
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
},
{
"i18n":{
"en":"Integrator"
},
"role":"integrator",
"permissions":[
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
},
{
"i18n":{
"en":"Guest"
},
"role":"guest",
"permissions":[],
"scope":"workspaces"
},
{
"i18n":{
"en":"Owner"
},
"role":"owner",
"permissions":[
"contracts.membership.edit",
"contracts.workspace.create",
"contracts.workspace.listAll",
"contracts.workspace.delete"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Owner"
},
"role":"owner",
"permissions":[
"workspaces.workspace.edit",
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
}
]
},
"relationships":{
"tenant":{
"data":{
"id":"{TENANT_ID}",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/{TENANT_ID}"
}
}
}
},
"meta":{},
"links":{
"self":"/v2/tenants/{TENANT_ID}/roles"
}
}
This resource allows you to retrieve all roles for a Tenant with the given ID.
HTTP Request
GET https://api.elastic.io/v2/tenants/{TENANT_ID}/roles
Authorization
This request is authorized for the users with the tenants.tenant.list_roles permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
Get the list of available permissions
Example Request:
curl https://api.elastic.io/v2/permissions
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":null,
"type":"permissions",
"attributes":{
"permissions":[
"contracts.contract.edit",
"contracts.membership.edit",
"contracts.workspace.create",
"contracts.workspace.listAll",
"contracts.workspace.delete",
"contracts.repository.edit",
"contracts.devTeam.edit",
"workspaces.workspace.edit",
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
]
}
},
"meta":{}
}
This endpoint returns all available permissions required for creating a role.
HTTP Request
GET https://api.elastic.io/v2/permissions
Authorization
This endpoint is available to all the platforms’ users. However, it does not list service permissions that are only available to Service Accounts. The list of service permissions is in the following table.
| Permission | Description |
|---|---|
global.flow.get_limited_to_stop |
Select flows that need to be stopped in limited Workspaces. Flow lifetime period is defined in the corresponding environment variable. |
tenants.user.create |
Create users in a Tenant. |
tenants.user.delete |
Remove users from a Platform. |
tenants.user.list_all |
List all users of a Tenant. |
tenants.user.get |
Get users by ID in a Tenant. |
tenants.tenant.edit |
Edit the Tenant. |
tenants.tenant.edit_roles |
Edit roles in a Tenant. |
tenants.tenant.list_roles |
Get the list of roles in a Tenant. |
tenants.tenant.create |
Create Tenants. |
tenants.tenant.delete |
Delete Tenants. |
tenants.tenant.get |
Get Tenants by ID. |
tenants.contract.create |
Create Contracts in a Tenant. |
tenants.membership.edit |
Grant or remove Tenant Admin role to Platform users. |
tenants.certificate.get_encrypted |
Get certificate and key in encrypted form. |
tenants.certificate.get_info |
Get certificate metadata. |
tenants.certificate.create |
Create certificates. |
tenants.certificate.edit |
Edit certificates. |
tenants.certificate.delete |
Delete certificates. |
tenants.oauth_clients.get |
Get a list of Oauth clients in a Tenant. |
tenants.oauth_clients.edit |
Edit Oauth clients in a Tenant. |
tenants.oauth_clients.create |
Create Oauth clients in a Tenant. |
tenants.oauth_clients.delete |
Delete Oauth clients in a Tenant. |
contracts.contract.get |
Get Contracts by ID. |
contracts.contract.edit_available_roles |
Edit available roles in a Contracts. |
contracts.membership.edit_directly |
Edit user membership by ID. |
contracts.contract.delete |
Delete Contracts. |
contracts.contract.finish_delete |
Stop all flows to delete the Contract. |
contracts.contract.finish_suspend |
Stop all flows to suspend the Contract. |
contracts.contract.suspend |
Request Contract suspension. |
contracts.contract.unsuspend |
Request Contract unsuspension. |
contracts.contract.listAll |
Get list of all contracts (Work in Progress!). |
contracts.contract.list_blocking_tasks |
List blocking tasks in the Contract. |
contracts.devTeam.edit_access |
Change repository access level. |
workspaces.workspace.edit_type |
Edit workspace type. |
workspaces.workspace.finish_delete |
Stop all flows to delete the Workspace. |
Update Tenant’s roles
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/roles
-X PATCH
-u {EMAIL}:{APIKEY}
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"tenant-policy",
"attributes":{
"roles":[
{
"role":"name_of_new_role",
"scope":"contracts",
"permissions":[
"contracts.workspace.create",
"contracts.devTeam.edit"
],
"i18n":{
"en":"new_role"
}
},
{
"role":"name_of_new_role",
"scope":"workspaces",
"permissions":[
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime"
],
"i18n":{
"en":"new_role"
}
}
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"type":"tenant-policy",
"attributes":{
"roles":[
{
"i18n":{
"en":"new_role"
},
"role":"name_of_new_role",
"permissions":[
"contracts.workspace.create",
"contracts.devTeam.edit"
],
"scope":"contracts"
},
{
"i18n":{
"en":"new_role"
},
"role":"name_of_new_role",
"permissions":[
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime"
],
"scope":"workspaces"
},
{
"i18n":{
"en":"Owner"
},
"role":"owner",
"permissions":[
"contracts.membership.edit",
"contracts.workspace.create",
"contracts.workspace.listAll",
"contracts.workspace.delete"
],
"scope":"contracts"
},
{
"i18n":{
"en":"Owner"
},
"role":"owner",
"permissions":[
"workspaces.workspace.edit",
"workspaces.flow.edit",
"workspaces.flow.toggleStatus",
"workspaces.flow.toggleRealtime",
"workspaces.credential.edit"
],
"scope":"workspaces"
}
]
},
"relationships":{
"tenant":{
"data":{
"id":"{TENANT_ID}",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/{TENANT_ID}"
}
}
}
},
"meta":{},
"links":{
"self":"/v2/tenants/{TENANT_ID}/roles"
}
}
This resource allows you to update the roles for a Tenant with the given ID.
HTTP Request
PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/roles
Authorization
This request is authorized for the users with the tenants.tenant.edit_roles permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “tenant-policy” |
| attributes.roles[] | yes | An array of Tenant’s roles. It can be empty. |
| attributes.roles[].role | no | Name of a role. |
| attributes.roles[].scope | no | The group of objects, which is affected by this role. Value can be “contracts” or “workspaces” |
| attributes.roles[].permissions[] | yes | An array of permissions. It can be empty. To get the list of available permissions execute Get the list of available permissions endpoint |
| attributes.roles[].i18n.{{language_key}} | no | The name of a role in different languages. The value is only required for “en” key. For other languages value is optional |
Create a SSL certificate
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"attributes":{
"publicKey":"{CERTIFICATE}",
"privateKey":"{RSA PRIVATE KEY}"
}
}'
Example Request (with attachment):
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: multipart/form-data'
--form "cert=@file"
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"5c6e9f68d5b4b60012a7a933",
"type":"certificate",
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe/certificates/5c6e9f68d5b4b60012a7a933"
},
"attributes":{
"publicKey":"{CERTIFICATE}",
"privateKey":"{RSA PRIVATE KEY}",
"salt":"3b07d847ba7580ea",
"iv":"2df1049e2e6395eb",
"owner":"5c4a0dde51a3d76ee8d6059d",
"tenant":"5c6e91b9d5b4b60012a796fe",
"algorithm":"aes-256-cbc",
"key_length":32
},
"relationships":{
"user":{
"data":{
"id":"5c4a0dde51a3d76ee8d6059d",
"type":"user"
},
"links":{
"self":"/v2/users/5c4a0dde51a3d76ee8d6059d"
}
},
"tenant":{
"data":{
"id":"5c6e91b9d5b4b60012a796fe",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
}
}
}
},
"meta":{
"version":2,
"subject":{
"commonName":"www.example.com"
},
"issuer":{
"commonName":"www.example.com"
},
"serial":"95098E44D7A54A6C",
"notBefore":"2019-01-21T15:26:29.000Z",
"notAfter":"2029-01-18T15:26:29.000Z",
"subjectHash":"c2b12038",
"signatureAlgorithm":"sha1WithRSAEncryption",
"fingerPrint":"DC:F9:D7:FA:A3:ED:71:1D:7A:B1:68:D1:A9:6F:66:99:62:72:F3:6D",
"publicKey":{
"algorithm":"sha1WithRSAEncryption"
},
"altNames":[],
"extensions":{
"subjectKeyIdentifier":"51:CC:13:79:84:DB:6D:CB:5F:17:BA:C4:4A:4B:A3:35:36:A2:C2:25",
"authorityKeyIdentifier":"keyid:51:CC:13:79:84:DB:6D:CB:5F:17:BA:C4:4A:4B:A3:35:36:A2:C2:25",
"basicConstraints":"CA:TRUE"
}
}
}
This resource allows you to create a new SSL certificate.
HTTP Request
POST https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates
Authorization
This request is authorized for the users with the tenants.certificate.create permission.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| attributes.publicKey | yes | CERTIFICATE |
| attributes.privateKey | yes | RSA PRIVATE KEY |
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
Returns
Returns SSL certificate object if the call succeeded
Retrieve a SSL certificate by id
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates/{CERTIFICATE_ID} \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c6eb8b36a6666001080d609",
"type":"certificate",
"links":{
"self":"/v2/tenants/5c6eb8a56a6666001080d5bc/certificates/5c6eb8b36a6666001080d609"
},
"attributes":{
"salt":"c27c8f8a273c5fe1",
"iv":"535e6289dd6d1d6e",
"owner":"5c4a0dde51a3d76ee8d6059d",
"tenant":"5c6eb8a56a6666001080d5bc",
"algorithm":"aes-256-cbc",
"key_length":32
},
"relationships":{
"user":{
"data":{
"id":"5c4a0dde51a3d76ee8d6059d",
"type":"user"
},
"links":{
"self":"/v2/users/5c4a0dde51a3d76ee8d6059d"
}
},
"tenant":{
"data":{
"id":"5c6eb8a56a6666001080d5bc",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/5c6eb8a56a6666001080d5bc"
}
}
}
},
"meta":{
"version":2,
"subject":{
"commonName":"www.example.com"
},
"issuer":{
"commonName":"www.example.com"
},
"serial":"95098E44D7A54A6C",
"notBefore":"2019-01-21T15:26:29.000Z",
"notAfter":"2029-01-18T15:26:29.000Z",
"subjectHash":"c2b12038",
"signatureAlgorithm":"sha1WithRSAEncryption",
"fingerPrint":"DC:F9:D7:FA:A3:ED:71:1D:7A:B1:68:D1:A9:6F:66:99:62:72:F3:6D",
"publicKey":{
"algorithm":"sha1WithRSAEncryption"
},
"altNames":[],
"extensions":{
"subjectKeyIdentifier":"51:CC:13:79:84:DB:6D:CB:5F:17:BA:C4:4A:4B:A3:35:36:A2:C2:25",
"authorityKeyIdentifier":"keyid:51:CC:13:79:84:DB:6D:CB:5F:17:BA:C4:4A:4B:A3:35:36:A2:C2:25",
"basicConstraints":"CA:TRUE"
}
}
}
This resource allows you to retrieve a SSL certificate with the given ID for the Tenant with the given ID.
HTTP Request
GET https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates/{CERTIFICATE_ID}
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
| CERTIFICATE_ID | The ID of the Certificate |
Authorization
This request is authorized for the users with the tenants.certificate.get_encrypted and/or tenants.certificate.get_info permissions.
Returns
Returns SSL certificate object if the call succeeded
Update a SSL certificate
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates/{CERTIFICATE_ID} \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"attributes":{
"publicKey":"{CERTIFICATE}",
"privateKey":"{RSA PRIVATE KEY}"
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c6e9f68d5b4b60012a7a933",
"type":"certificate",
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe/certificates/5c6e9f68d5b4b60012a7a933"
},
"attributes":{
"privte_key":"{CERTIFICATE}",
"public_key":"{RSA PRIVATE KEY}",
"salt":"3b07d847ba7580ea",
"iv":"2df1049e2e6395eb",
"owner":"5c4a0dde51a3d76ee8d6059d",
"tenant":"5c6e91b9d5b4b60012a796fe",
"algorithm":"aes-256-cbc",
"key_length":32
},
"relationships":{
"user":{
"data":{
"id":"5c4a0dde51a3d76ee8d6059d",
"type":"user"
},
"links":{
"self":"/v2/users/5c4a0dde51a3d76ee8d6059d"
}
},
"tenant":{
"data":{
"id":"5c6e91b9d5b4b60012a796fe",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/5c6e91b9d5b4b60012a796fe"
}
}
}
},
"meta":{
"version":2,
"subject":{
"commonName":"www.example.com"
},
"issuer":{
"commonName":"www.example.com"
},
"serial":"95098E44D7A54A6C",
"notBefore":"2019-01-21T15:26:29.000Z",
"notAfter":"2029-01-18T15:26:29.000Z",
"subjectHash":"c2b12038",
"signatureAlgorithm":"sha1WithRSAEncryption",
"fingerPrint":"DC:F9:D7:FA:A3:ED:71:1D:7A:B1:68:D1:A9:6F:66:99:62:72:F3:6D",
"publicKey":{
"algorithm":"sha1WithRSAEncryption"
},
"altNames":[],
"extensions":{
"subjectKeyIdentifier":"51:CC:13:79:84:DB:6D:CB:5F:17:BA:C4:4A:4B:A3:35:36:A2:C2:25",
"authorityKeyIdentifier":"keyid:51:CC:13:79:84:DB:6D:CB:5F:17:BA:C4:4A:4B:A3:35:36:A2:C2:25",
"basicConstraints":"CA:TRUE"
}
}
}
This resource allows you to update a SSL certificate with the given ID for the Tenant with the given ID.
HTTP Request
PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates/{CERTIFICATE_ID}
Authorization
This request is authorized for the users with the tenants.certificate.edit permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
| CERTIFICATE_ID | The ID of the Certificate |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| attributes.publicKey | yes | CERTIFICATE |
| attributes.privateKey | yes | RSA PRIVATE KEY |
Returns
Returns SSL Certificate object if the call succeeded
Delete Certificate
Example Request:
curl -i https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates/{CERTIFICATE_ID} \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
This resource allows you to delete a SSL certificate with the given ID for the Tenant with the given ID.
HTTP Request
DELETE https://api.elastic.io/v2/tenants/{TENANT_ID}/certificates/{CERTIFICATE_ID} \
Authorization
This request is authorized for the users with the tenants.certificate.delete permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
| CERTIFICATE_ID | The ID of the Certificate |
Returns
Responds with the 204 No content message if the call succeeded (with empty body).
Granting Tenant Admin’s permissions to the User
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/members/{USER_ID}/ \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "tenant-member"
"attributes": {
"roles": [
"tenant-admin"
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c06a22e0aba010011aba767",
"type":"tenant-member",
"attributes":{
"roles":[
"tenant-admin"
]
},
"relationships":{
"user":{
"data":{
"id":"5c06a22e0aba010011aba767",
"type":"user"
},
"links":{
"self":"/v2/users/5c06a22e0aba010011aba767"
}
},
"tenant":{
"data":{
"id":"56c207adb9121181e650c0ef",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/56c207adb9121181e650c0ef"
}
}
}
},
"meta":{}
}
This endpoint allows you to grant Tenant Admin’s permissions to the User with the given ID in the Tenant with the given ID.
HTTP Request
PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/members/{USER_ID}/
Authorization
This request is authorized for the users with the tenants.membership.edit permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
| USER_ID | The ID of the user to be updated |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be the “tenant-member”. |
| attributes.roles[] | yes | A value should be the “tenant-admin”. |
Returns
Returns the member’s object if the call succeeded
Remove Tenant Admin’s permissions from the user
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/members/{USER_ID}/ \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "tenant-member"
"attributes": {
"roles": []
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c06a22e0aba010011aba767",
"type":"tenant-member",
"attributes":{
"roles":[]
},
"relationships":{
"user":{
"data":{
"id":"5c06a22e0aba010011aba767",
"type":"user"
},
"links":{
"self":"/v2/users/5c06a22e0aba010011aba767"
}
},
"tenant":{
"data":{
"id":"56c207adb9121181e650c0ef",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/56c207adb9121181e650c0ef"
}
}
}
},
"meta":{}
}
This endpoint allows you to remove Tenant Admin’s permissions from the User with the given ID in the Tenant with the given ID.
HTTP Request
PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/members/{USER_ID}/
Authorization
This request is authorized for the users with the tenants.membership.edit permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
| USER_ID | The ID of the user to be updated |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be the “tenant-member”. |
| attributes.roles[] | yes | A value should be an empty array. |
Returns
Returns the member’s object if the call succeeded
Create an Oauth-client
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"oauth-client",
"attributes":{
"client_id":"{CLIENT_ID}",
"client_secret":"{CLIENT_SECRET}"
},
"relationships":{
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"5c80e6b9bb0d200011993332",
"type":"oauth-client",
"attributes":{
"client_id":"560e5a2323d480a00000002",
"client_secret":"c7e56633-5e88-4c97-8da9-3243423412"
},
"relationships":{
"component":{
"data":{
"id":"5a0c4f03718f9700132d88ef",
"type":"component"
},
"links":{
"self":"/v2/components/5a0c4f03718f9732197d88ef"
}
}
}
},
"meta":{}
}
This resource allows you to create a new Oauth-client. You can create just only one oauth-client for a component per tenant.
HTTP Request
POST https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients
Authorization
This request is authorized for the users with the tenants.oauth_clients.create permission.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “oauth-client” |
| attributes.client_id | yes | Oauth-client ID |
| attributes.client_secret | yes | Oauth-client secret |
| relationships.component.data.id | yes | Component ID |
| relationships.component.data.type | yes | A value should be “component” |
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
Returns
Returns Oauth-client object if the call succeeded
Retrieve an Oauth-client
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients \
-u {EMAIL}:{APIKEY}
Example Request (with filter):
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients/?filter[component]={{COMPONENT_ID}} \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"5c80e6b9bb0d200011333d92",
"type":"oauth-client",
"attributes":{
"client_id":"560e5a27734d423233200002",
"client_secret":"c7e56633-5e88-4c97-8da9-f823432423"
},
"relationships":{
"component":{
"data":{
"id":"5a0c4f03718f9700197328ef",
"type":"component"
},
"links":{
"self":"/v2/components/5a0c4f03718f97232397d88ef"
}
}
}
},
{
"id":"5c7d0c362bcf5d0011323b44",
"type":"oauth-client",
"attributes":{
"client_id":"560e5a27734d4802131200001",
"client_secret":"c7e56633-5e88-4c97-8da9-f821232311"
}
}
],
"meta":{}
}
This resource allows you to retrieve Oauth-clients for the Tenant with the given ID.
HTTP Request
GET https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| TENANT_ID | yes | The ID of the Tenant |
| filter[component] | no | Filter by component_id |
Authorization
This request is authorized for the users with the tenants.oauth_clients.get permission.
Returns
Returns Oauth-client object if the call succeeded
Retrieve an Oauth-client by id
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients/{OAUTH-CLIENT_ID} \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c80e6b9bb0d200033993d92",
"type":"oauth-client",
"attributes":{
"client_id":"560e5a27734d480a23424302",
"client_secret":"c7e56633-5e88-4c97-8da9-f82232439d4a7"
},
"relationships":{
"component":{
"data":{
"id":"5a0c4f03718f9700197d88ef",
"type":"component"
},
"links":{
"self":"/v2/components/5a0c4f03718f934134ef"
}
}
}
},
"meta":{}
}
This resource allows you to retrieve a Oauth-client with the given ID for the Tenant with the given ID.
HTTP Request
GET https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients/{OAUTH-CLIENT_ID}
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| TENANT_ID | yes | The ID of the Tenant |
| OAUTH-CLIENT_ID | yes | The ID of the Oauth-client |
Authorization
This request is authorized for the users with the tenants.oauth_clients.get permission.
Returns
Returns Oauth-client object if the call succeeded
Update an Oauth-client
Example Request:
curl https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients/{OAUTH-CLIENT_ID} \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"oauth-client",
"attributes":{
"client_id":"{CLIENT_ID}",
"client_secret":"{CLIENT_SECRET}"
},
"relationships":{
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
}
}
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5c80e6b9bb0d2000345433d92",
"type":"oauth-client",
"attributes":{
"client_id":"56127089f76793453453402",
"client_secret":"c7e56148-5e84-4c97-8da9-f82345357"
},
"relationships":{
"component":{
"data":{
"id":"5a0c4f03718f97001345348ef",
"type":"component"
},
"links":{
"self":"/v2/components/5a0c4f03718f97435348ef"
}
}
}
},
"meta":{}
}
This resource allows you to update an Oauth-client with the given ID for the Tenant with the given ID.
HTTP Request
PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients/{OAUTH-CLIENT_ID}
Authorization
This request is authorized for the users with the tenants.oauth_clients.edit permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
| OAUTH-CLIENT_ID | The ID of the Oauth-client |
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “oauth-client” |
| attributes.client_id | yes | Oauth-client ID |
| attributes.client_secret | yes | Oauth-client secret |
| relationships.component.data.id | yes | Component ID |
| relationships.component.data.type | yes | A value should be “component” |
Returns
Returns Oauth-client object if the call succeeded
Delete an Oauth-client
Example Request:
curl -i https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients/{OAUTH-CLIENT_ID} \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
This resource allows you to delete a Oauth-client with the given ID for the Tenant with the given ID.
HTTP Request
DELETE https://api.elastic.io/v2/tenants/{TENANT_ID}/oauth-clients/{OAUTH-CLIENT_ID} \
Authorization
This request is authorized for the users with the tenants.oauth_clients.delete permission.
URL Parameters
| Parameter | Description |
|---|---|
| TENANT_ID | The ID of the Tenant |
| OAUTH-CLIENT_ID | The ID of the Oauth-client |
Returns
Responds with the 204 No content message 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'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"59d22e7eeb865b0018adc248",
"type":"user",
"links":{
"self":"/v2/users/59d22e7eeb865b0018adc248"
},
"attributes":{
"first_name":"John",
"last_name":"Doe",
"email":"test@example.com",
"registered":"2017-10-02T12:18:06.274Z",
"last_login":"2018-03-15T16:53:57.696Z"
}
},
"meta":{}
}
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'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"59d3562c68ed850019bde27f",
"type":"user",
"links":{
"self":"/v2/users/59d3562c68ed850019bde27f"
},
"attributes":{
"first_name":"John",
"last_name":"Doe",
"email":"test@example.com",
"registered":"2017-10-03T09:19:40.598Z",
"last_login":"2018-03-16T10:30:38.656Z"
}
},
"meta":{}
}
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 |
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
{
"data":[
{
"id":"560e5a27734d480a00000002",
"type":"user",
"links":{
"self":"/v2/users/560e5a27734d480a00000002"
},
"attributes":{
"first_name":"John",
"last_name":"Doe",
"email":"test@example.com",
"registered":"2015-10-02T10:19:19.697Z",
"last_login":"2018-02-08T16:07:52.495Z"
}
}
],
"meta":{
"page":1,
"per_page":1,
"total":646,
"total_pages":646
}
}
Example Request (default paging):
curl https://api.elastic.io/v2/users/ \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
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"
}
},
{
"id":"588f8b04b84a6a7f3e47668e",
"type":"user",
"attributes":{
"first_name":"Eulalia",
"last_name":"Hyatt",
"email":"user-2@my.org"
}
},
{
"id":"588f8b04b84a6a7f3e47668f",
"type":"user",
"attributes":{
"first_name":"Bertram",
"last_name":"Davis",
"email":"user-1@aliens.org"
}
},
{
"id":"588f8b04b84a6a7f3e476690",
"type":"user",
"attributes":{
"first_name":"Marianne",
"last_name":"Sawayn",
"email":"client@outcast.org"
}
},
{
"id":"588f8b04b84a6a7f3e476691",
"type":"user",
"attributes":{
"first_name":"Esta",
"last_name":"Abbott",
"email":"another@outcast.org"
}
},
{
"id":"588f8b04b84a6a7f3e476692",
"type":"user",
"attributes":{
"first_name":"Kayleigh",
"last_name":"Howell",
"email":"tenant-admin@example.com"
}
}
]
}
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 you want to display | 1 |
Authorization
This request is authorized for the users with the tenants.user.list_all permission.
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":"Secret1%"
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"5aabc258bd6d6400079b4592",
"type":"user",
"links":{
"self":"/v2/users/5aabc258bd6d6400079b4592"
},
"attributes":{
"first_name":"John",
"last_name":"Doe",
"email":"test@example.com",
"registered":"2018-03-16T13:10:48.221Z",
"last_login":"2018-03-16T13:10:48.221Z"
}
},
"meta":{}
}
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. Password should be at least 8 characters long and include letters, numbers and special symbols. |
Authorization
This request is authorized for the users with the tenants.user.create permission.
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}
Example Response:
HTTP/1.1 204 No Content
This resource allows you to delete a user.
When a User is deleted the following data will be deleted as well:
- SSH keys
- User’s object itself
- all Workspaces and Contracts, where the User is the only member
Not deleted immediately
These data objects are deleted automatically (e.g. due to expiration), hence won’t be deleted right after User deletion:
- Flows activity records (which used in order to show runlog)
- Logs of flow execution and repo build
- Invitations to the Team, Contract and Workspace
- Notifications
Data associated with Contract and Workspace
- If this User is a member of any Contract which has one more Owner beside him/her then User’s Teams and Repos will be transferred to the next Owner.
- If this User is a member of any Workspace which has one more Owner beside him/her then User’s Flows and Credentials will be transferred to the next Owner.
- If this User is the last Owner of any Workspace then given Workspace will be deleted with all data.
- If this User is the only member of Contract(s) then he/she will be deleted along with Contract and all the unique data connected with this User.
Authorization
This request is authorized for the users with the tenants.user.delete permission.
HTTP Request
DELETE https://api.elastic.io/v2/users/{USER_ID}
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| USER_ID | yes | User identifier |
Workspaces
What is a Workspace unit?
A Workspace is a space where every user can work on an integration project independently or in collaboration with other users. Each Workspace can have more than one member. All members of a Workspace have their roles. To get all available roles, please execute the “Get the Contract’s roles” endpoint. There is one predefined role - Workspace Owner. This role gives the holder all the rights within the Workspace unit, it cannot be deleted and the permissions’ set cannot be changed. Each role is limited to the given Workspace only. The same user in the platform can have different roles in different Workspaces.
Get Workspace by ID
Example Request:
curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}?include=members,invites \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"59d341e9037f7200184a408b",
"type":"workspace",
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
},
"attributes":{
"name":"My Workspace"
},
"relationships":{
"contract":{
"data":{
"id":"5b4f337bff4304610483ba67",
"type":"contract"
},
"links":{
"self":"/v2/contracts/5b4f337bff4304610483ba67"
}
},
"members":{
"data":[
{
"id":"571634ecfdf77f0800000005",
"type":"member"
},
{
"id":"58c6b20124901200184fdfd1",
"type":"member"
}
],
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b/members/"
}
},
"invites":{
"data":[
{
"id":"5b6460f73beeff001074af5b",
"type":"workspace-invite"
}
],
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b/invites/"
}
}
}
},
"meta":{},
"included":[
{
"id":"560e5a27734d480a00000002",
"type":"member",
"links":{
"self":"/v2/members/560e5a27734d480a00000002"
},
"attributes":{
"first_name":"John",
"last_name":"Doe",
"roles":[
"admin"
],
"email":"john@doe.com"
}
},
{
"id":"5612c1e983dd4f0600000002",
"type":"member",
"links":{
"self":"/v2/members/5612c1e983dd4f0600000002"
},
"attributes":{
"first_name":"Bob",
"last_name":"Smith",
"roles":[
"admin"
],
"email":"bob@smith.com"
}
},
{
"id":"5b6460f73beeff001074af5b",
"type":"workspace-invite",
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b/invite/5b6460f73beeff001074af5b"
},
"attributes":{
"email":"test@user.com",
"roles":[
"admin"
]
}
}
],
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
}
}
This endpoints returns a Workspace object for certain Workspace ID.
HTTP Request
GET https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/
Authorization
User has to be a member of the Workspace.
URL Parameters
| Parameter | Description |
|---|---|
| WORKSPACE_ID | The ID of the Workspace |
URL Query Parameters
| Parameter | Required | Description |
|---|---|---|
| include | no | Include full resource objects in response for related entities, or not. Possible values: members and/or invites. |
Get User’s Workspaces
Example Request:
curl https://api.elastic.io/v2/workspaces?contract_id={CONTRACT_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"59d341e9037f7200184a408b",
"type":"workspace",
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b"
},
"attributes":{
"name":"My first Workspace"
},
"relationships":{
"contract":{
"data":{
"id":"5b4f337bff4304610483ba67",
"type":"contract"
},
"links":{
"self":"/v2/contracts/5b4f337bff4304610483ba67"
}
},
"members":{
"data":[
{
"id":"571634ecfdf77f0800000005",
"type":"member"
},
{
"id":"58c6b20124901200184fdfd1",
"type":"member"
}
],
"links":{
"self":"/v2/workspaces/59d341e9037f7200184a408b/members/"
}
}
}
},
{
"id":"5b6d97bf033b500011fef487",
"type":"workspace",
"links":{
"self":"/v2/workspaces/5b6d97bf033b500011fef487"
},
"attributes":{
"name":"My second Workspace"
},
"relationships":{
"contract":{
"data":{
"id":"5b4f337bff4304610483ba67",
"type":"contract"
},
"links":{
"self":"/v2/contracts/5b4f337bff4304610483ba67"
}
},
"members":{
"data":[
{
"id":"59d22e7eeb865b0018adc248",
"type":"member"
},
{
"id":"5b6d54a8bc7cf60010e34536",
"type":"member"
},
{
"id":"5b6da6e9bff5630010f2024f",
"type":"member"
}
],
"links":{
"self":"/v2/workspaces/5b6d97bf033b500011fef487/members/"
}
}
}
}
],
"meta":{},
"links":{
"self":"/v2/workspaces"
}
}
This endpoint returns a list of Workspaces which belong to the given User.
HTTP Request
GET https://api.elastic.io/v2/workspaces?contract_id={CONTRACT_ID}
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| contract_id | no | An Id of the Contract |
Authorization
User has to be a member of the Workspace.
Get a list of members of Workspace
Example Request:
curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/members/ \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"59d22e7eeb865b0018adc248",
"type":"member",
"links":{
"self":"/v2/members/59d22e7eeb865b0018adc248"
},
"attributes":{
"first_name":"Marilyn",
"last_name":"Manson",
"roles":[
"admin"
],
"email":"marilyn@manson.com"
}
},
{
"id":"5b6da6e9bff5630010f2024f",
"type":"member",
"links":{
"self":"/v2/members/5b6da6e9bff5630010f2024f"
},
"attributes":{
"first_name":"Ozzy",
"last_name":"Osborn",
"roles":[
"integrator"
],
"email":"ozzy@osborn.com"
}
}
],
"meta":{},
"links":{
"self":"/v2/workspaces/5b6d97bf033b500011fef487/members"
}
}
This endpoints returns a list of all members of certain Workspace.
HTTP Request
GET https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/members/
Authorization
User has to be a member of the Workspace.
URL Parameters
| Parameter | Description |
|---|---|
| WORKSPACE_ID | The ID of the Workspace |
Create a Workspace
Example Request:
curl https://api.elastic.io/v2/workspaces \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"workspace",
"attributes":{
"name":"My test Workspace from API"
},
"relationships":{
"contract":{
"data":{
"id":"{CONTRACT_ID}",
"type":"contract"
}
}
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5b880121f3c1a800112a3bb3",
"type":"workspace",
"links":{
"self":"/v2/workspaces/5b880121f3c1a800112a3bb3"
},
"attributes":{
"name":"My first Workspace from API",
"type":"full"
},
"relationships":{
"contract":{
"data":{
"id":"5b4f337bff4304610483ba67",
"type":"contract"
},
"links":{
"self":"/v2/contracts/5b4f337bff4304610483ba67"
}
},
"members":{
"data":[
{
"id":"59d22e7eeb865b0018adc248",
"type":"member"
}
],
"links":{
"self":"/v2/workspaces/5b880121f3c1a800112a3bb3/members/"
}
}
}
},
"meta":{}
}
This endpoint allows creating a Workspace only by the User that is a member of the Contract’s scope.
HTTP Request
POST https://api.elastic.io/v2/workspaces
Authorization
This request is authorized for the contract’s scope members with the contracts.workspace.create permission.
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “workspace” |
| attributes.name | yes | Name of the Workspace |
| relationships.contract.data.id | yes | An Id of the contract |
| relationships.contract.data.type | yes | A value must be “contract” |
Returns
Returns Workspace object if the call succeeded
Update a Workspace
Example Request:
curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID} \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"workspace",
"attributes":{
"name":"New Workspace Name",
"type":"limited"
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace",
"links":{
"self":"/v2/workspaces/{WORKSPACE_ID}"
},
"attributes":{
"name":"New Workspace Name",
"type":"full"
},
"relationships":{
"contract":{
"data":{
"id":"{CONTRACT_ID}",
"type":"contract"
},
"links":{
"self":"/v2/contracts/{CONTRACT_ID}"
}
},
"members":{
"data":[
{
"id":"{USER_ID}",
"type":"member"
}
],
"links":{
"self":"/v2/workspaces/{WORKSPACE_ID}/members/"
}
}
}
},
"meta":{}
}
This endpoint allows to update Workspace name.
HTTP Request
PATCH https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}
Authorization
The request to update the name of Workspace is authorized for the contract’s scope members with the workspaces.workspace.edit permission.
To update the type of Workspace this request is authorized for users with the workspaces.workspace.edit_type permission.
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “workspace” |
| attributes.name | yes | Name of the Workspace |
| attributes.type | no | Type of the Workspace. The value must be full or limited |
Returns
Returns Workspace object if the call succeeded
Add a new member to Workspace
Example Request:
curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/members/ \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "member",
"id": "{USER_ID}",
"attributes": {
"roles": [
"{ROLE_1}",
"{ROLE_2}"
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"571634ecfdf77f0800000005",
"type":"member",
"links":{
"self":"/v2/members/571634ecfdf77f0800000005"
},
"attributes":{
"first_name":"Iggy",
"last_name":"Pop",
"roles": [
"{ROLE_1}",
"{ROLE_2}"
]
"email":"iggy@pop.com"
}
},
"meta":{}
}
This endpoint allows you to add a User to a certain Workspace as a member. You can add User only from the Contract, which current Workspace belongs to. A notification email will be sent. The User becomes a member immediately.
HTTP Request
POST https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/members
Authorization
This request is authorized for a User with workspaces.workspace.edit permission only.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| id | yes | id of an already registered user, who will be added as a member of the Workspace |
| type | yes | A value should be “member”. |
| attributes.roles[] | yes | To get all available roles, please execute the “Get the Contract’s roles” endpoint. |
Returns
Returns member object if the call succeeded
Update membership in Workspace
Example Request:
curl https://api.elastic.io/v2/workspaces/{WORKSPACE_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": {
"roles": [
"{NEW_ROLE}"
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"59f747c33f1d3c001901a44e",
"type":"member",
"links":{
"self":"/v2/members/59f747c33f1d3c001901a44e"
},
"attributes":{
"roles": [
"{NEW_ROLE}"
]
}
},
"meta":{}
}
This endpoint allows updating a membership of a given User. Only roles attribute can be updated.
HTTP Request
PATCH https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/members/{USER_ID}/
Authorization
This request is authorized for Workspace members with permission workspaces.workspace.edit.
URL Parameters
| Parameter | Description |
|---|---|
| WORKSPACE_ID | The ID of the Workspace |
| 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.roles[] | yes | To get all available roles, please execute the “Get the Contract’s roles” endpoint. |
Returns
Returns member object if the call succeeded
Remove member from Workspace
Example Request:
curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/members/{USER_ID}/ \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
Remove a membership of the User in the Workspace. Ownership of those user’s associated data will be transferred to the User performing this operation:
- Flows
- Credentials
- DataSamples
HTTP Request
DELETE https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/members/{USER_ID}/
Authorization
This request is authorized for Workspace members with permission workspaces.workspace.edit.
URL Parameters
| Parameter | Description |
|---|---|
| WORKSPACE_ID | The ID of the Workspace |
| USER_ID | The ID of the user, which should leave the Workspace |
Returns
Responds with 204 No content if the call succeeded (with empty body).
Delete Workspace
Example Request:
curl -i https://api.elastic.io/v2/workspaces/{WORKSPACE_ID} \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
This endpoint will delete the Workspace along with the following items that were inside the Workspace:
- Credentials
- Agents
- DataSamples
- InviteTokens
- Lookups
- Flow’s DynamicMetadata
- Flow’s DynamicSelectModel
- Flow’s ExecStat
- Flow’s ExecutionResult
- Flow’s MarathonEvent
- Flow’s RequestBin
- Flow’s TaskHooksData
- Flow’s TaskStats
- Flow’s TaskStatError
- Flow’s TaskVersion
*Note, that the deletion process is asynchronous. Actual deletion of all data will be performed after API response, because it will take some time to terminate all containers of Workspace’s flows. *
HTTP Request
DELETE https://api.elastic.io/v2/workspaces/{WORKSPACE_ID} \
Authorization
This request can be performed by either the Contract’s user (the current Workspace assigned to) with the contracts.workspace.delete permission or just the Workspace’s user with the workspaces.workspace.edit permission.
URL Parameters
| Parameter | Description |
|---|---|
| {WORKSPACE_ID} | The ID of the Workspace |
Returns
Responds with 204 No content if the call succeeded (with empty body).