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.

Create 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	Allowed value: `agent`
attributes.title	yes	Agent title
attributes.description	yes	Agent description
relationships.workspace.data.id	yes	Workspace ID
relationships.workspace.data.type	yes	Allowed value: `workspace`

Returns

Returns the created agent object.

Auth Clients (Experimental)

In order to use an OAuth2 based Component in the platform it is required to register a client at the authorization server. Upon registration the authorization server issues the registered client an identifier (client ID) and a secret. These client credentials are used to create a client using the following API.

Retrieve All Auth Clients

Example Request:

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

Example Response:

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

{
  "data": [
    {
      "id": "{AUTH-CLIENT_ID}",
      "type": "auth-client",
      "attributes": {
        "type": "oauth2",
        "name": "Auth client",
        "credentials": {
          "client_id": "{CLIENT_ID}",
          "client_secret": "{CLIENT_SECRET}",
          "refresh_token_url": "http://example.com"
        }
      },
      "relationships": {
        "components": {
          "data": [
            {
              "id": "{COMPONENT_ID}",
              "type": "component"
            }
          ]
        },
        "tenant": {
          "data": {
            "id": "{TENANT_ID}",
            "type": "tenant"
          },
          "links": {
            "self": "/v2/tenants/{TENANT_ID}"
          }
        }
      },
      "links": {
        "self": "/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
      }
    }
  ],
  "meta": {}
}

This resource allows you to retrieve all the Auth-clients belonging to the given Tenant.

HTTP Request

GET https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients

Authorization

This request is authorized for the tenant’s scope members with the tenants.auth_clients.get permission.

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	Tenant ID

Query Parameters

Parameter	Required	Description
filter[component]	no	Filter the Auth Clients only for specific component. Must be `id` of `Component`

Returns

Returns all the Auth-clients belonging to the given Tenant.

Create Auth Client

Example Request:

curl https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
    {
    "data":{
      "type":"auth-client",
      "attributes":{
        "type":"oauth2",
        "name":"Auth client",
        "credentials":{
          "client_id":"{CLIENT_ID}",
          "client_secret":"{CLIENT_SECRET}",
          "refresh_token_url":"http://example.com"
        }
      },
      "relationships":{
        "components":{
          "data":[
            {
              "id":"{COMPONENT_ID}",
              "type":"component"
            }
          ]
        }
      }
    }
  }'

Example Response:

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

{
  "data": {
    "id": "{AUTH-CLIENT_ID}",
    "type": "auth-client",
    "attributes": {
      "type": "oauth2",
      "name": "Auth client",
      "credentials": {
        "client_id": "{CLIENT_ID}",
        "client_secret": "{CLIENT_SECRET}",
        "refresh_token_url": "http://example.com"
      }
    },
    "relationships": {
      "components": {
        "data": [
          {
            "id": "{COMPONENT_ID}",
            "type": "component"
          }
        ]
      },
      "tenant": {
        "data": {
          "id": "{TENANT_ID}",
          "type": "tenant"
        },
        "links": {
          "self": "/v2/tenants/{TENANT_ID}"
        }
      }
    },
    "links": {
      "self": "/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
    }
  },
  "meta": {}
}

This resource allows you to create an Auth-client.

HTTP Request

POST https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients

Authorization

This request is authorized for the tenant’s scope members with the tenants.auth_clients.create permission.

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	Tenant ID

Body Parameters

Parameter	Required	Description
type	yes	Allowed value: `auth-client`
attributes.name	yes	Auth Client name
attributes.type	yes	Auth Client type. May be any of: `oauth2`, `other`
attributes.credentials	yes	Auth Client credentials
attributes.credentials.client_id	yes (if `attributes.type` is `oauth2`)	Auth Client client ID
attributes.credentials.client_secret	yes (if `attributes.type` is `oauth2`)	Auth Client client secret
attributes.credentials.refresh_token_url	yes (if `attributes.type` is `oauth2`)	Auth Client refresh token URL
relationships.components.data[].component.type	yes	Allowed value: `component`
relationships.components.data[].component.id	yes	Component ID

Returns

Returns the created Auth Client object.

Retrieve the Auth Client by ID

Example Request:

curl https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID} \
   -u {EMAIL}:{APIKEY}

Example Response:

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


{
  "data": {
    "id": "{AUTH-CLIENT_ID}",
    "type": "auth-client",
    "attributes": {
      "type": "oauth2",
      "name": "Auth client",
      "credentials": {
        "client_id": "{CLIENT_ID}",
        "client_secret": "{CLIENT_SECRET}",
        "refresh_token_url": "http://example.com"
      }
    },
    "relationships": {
      "components": {
        "data": [
          {
            "id": "{COMPONENT_ID}",
            "type": "component"
          }
        ]
      },
      "tenant": {
        "data": {
          "id": "{TENANT_ID}",
          "type": "tenant"
        },
        "links": {
          "self": "/v2/tenants/{TENANT_ID}"
        }
      }
    },
    "links": {
      "self": "/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
    }
  },
  "meta": {}
}

This resource allows you to retrieve an Auth Client by its ID. If the Auth Client with given ID does not belong to the current Tenant, an error will be returned.

HTTP Request

GET https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}

Authorization

This request is authorized for the tenant’s scope members with the tenants.auth_clients.get permission.

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	Tenant ID
AUTH-CLIENT_ID	yes	Auth Client ID

Returns

The Auth Client with given ID

Update the Auth Client

Example Request:

curl https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID} \
   -X PATCH \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
   {
    "data":{
      "id":"{AUTH-CLIENT_ID}",
      "type":"auth-client",
      "attributes":{
        "name":"Auth client"
      },
      "relationships":{
        "components":{
          "data":[
            {
              "id":"{COMPONENT_ID}",
              "type":"component"
            }
          ]
        }
      }
    }
  }'

Example Response:

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

{
   "data":{
      "id":"{AUTH-CLIENT_ID}",
      "type":"auth-client",
      "attributes":{
         "type":"oauth2",
         "name":"Auth client",
         "credentials":{
           "client_id": "{CLIENT_ID}",
           "client_secret": "{CLIENT_SECRET}",
           "refresh_token_url": "http://example.com"
         }
      },
      "relationships":{
        "components": {
          "data": [
            {
              "id": "{COMPONENT_ID}",
              "type": "component"
            }
          ]
        },
         "tenant":{
            "data":{
               "id":"{TENANT_ID}",
               "type":"tenant"
            },
            "links":{
               "self":"/v2/tenants/{TENANT_ID}"
            }
         }
      },
     "links":{
       "self":"/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
     }
   },
   "meta":{}
}

This resource allows you to update the Auth Client. If the Auth Client with type oauth2 then you can update only name and linked components, otherwise if the type is other, then you can put in credentials any data that you want and add components which can use this Auth Client.

HTTP Request

PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}

Authorization

This request is authorized for the tenant’s scope members with the tenants.auth_clients.edit permission.

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	Tenant ID
AUTH-CLIENT_ID	yes	Auth Client ID

Body Parameters

Parameter	Required	Description
type	yes	Allowed value: `auth-client`
attributes.name	no	New name of the Auth Client
attributes.credentials	no (not allowed for `oauth2` type)	Auth Client credentials
relationships.components.data[].component.type	no	Allowed value: `component`
relationships.components.data[].component.id	no	Component ID

Returns

Returns the updated Auth Client object.

Delete Auth Client

Example Request:

curl https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID} \
   -X DELETE \
   -u {EMAIL}:{APIKEY}

This resource allows you to delete an Auth Client. You can’t delete an Auth Client, while it has one or more secrets attached.

HTTP Request

DELETE {{ api_base_url }/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}

Authorization

This request is authorized for the Tenant’s scope members with the tenants.auth_clients.delete permission.

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	Tenant ID
AUTH-CLIENT_ID	yes	Auth Client ID

Example Response:

HTTP/1.1 204 No Content

Auth Secrets (Experimental)

The Secret is used to expose the information that the platform needs to collect from the integrator in order to be able to connect to their instance/account. The information collected typically includes:

URL to the integrator’s instance
Username or other account ID
Password or other API keys/tokens required to authenticate

Retrieve All Auth Secrets

Example Request:

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

Example Response:

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

{
   "data":[
      {
         "id":"{AUTH-SECRET_ID}",
         "type":"auth-secret",
         "attributes":{
            "name":"Auth secret",
            "state":"ready",
            "credentials":{
              "access_token": "{ACCESS_TOKEN}",
              "refresh_token": "{REFRESH_TOKEN}",
              "expires_in": "{EXPIRES_IN}"
            }
         },
         "relationships":{
            "workspace":{
               "data":{
                  "id":"{WORKSPACE_ID}",
                  "type":"workspace"
               },
               "links":{
                  "self":"/v2/workspace/{WORKSPACE_ID}"
               }
            },
            "user":{
               "data":{
                  "id":"{USER_ID}",
                  "type":"user"
               },
               "links":{
                  "self":"/v2/users/{USER_ID}"
               }
            },
            "auth-client":{
               "data":{
                  "id":"{AUTH-CLIENT_ID}",
                  "type":"auth-client"
               },
               "links":{
                  "self":"/v2/tenantns/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
               }
            }
         },
        "links":{
          "self":"/v2/workspace/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}"
        }
      }
   ],
   "meta":{}
}

This resource allows you to retrieve all the Auth Secrets belonging to the given Workspace.

HTTP Request

GET https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets

Authorization

This request is authorized for the Workspace’s scope members with the workspaces.auth_secret.get permission.

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	yes	Workspace ID

Query Parameters

Parameter	Required	Description
filter[user]	no	Filter the Auth Secrets only for specific User. Must be `id` of `User`
filter[auth_client]	no	Filter the Auth Secrets only for specific Auth-client. Must be `id` of `Auth-client`

Returns

Returns all the Auth Secrets belonging to the given Workspace.

Create Auth Secret

Example Request:

curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
    {
     "data":{
       "type":"auth-secret",
       "attributes":{
          "name":"Auth secret",
          "state":"error",
          "error":"Something went technical wrong",
          "credentials":{
            "access_token": "{ACCESS_TOKEN}",
            "refresh_token": "{REFRESH_TOKEN}",
            "expires_in": "{EXPIRES_IN}"
          }
       },
       "relationships":{
          "auth-client":{
             "data":{
                "id":"{AUTH-CLIENT_ID}",
                "type":"auth-client"
             }
          }
       }
   }'

Example Response:

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

{
  "data":{
     "id":"{AUTH-SECRET_ID}",
     "type":"auth-secret",
     "attributes":{
        "name":"Auth secret",
        "state":"error",
        "error":"Something went technical wrong",
        "credentials":{
          "access_token": "{ACCESS_TOKEN}",
          "refresh_token": "{REFRESH_TOKEN}",
          "expires_in": "{EXPIRES_IN}"
        }
     },
     "relationships":{
        "workspace":{
           "data":{
              "id":"{WORKSPACE_ID}",
              "type":"workspace"
           },
           "links":{
              "self":"/v2/workspace/{WORKSPACE_ID}"
           }
        },
        "user":{
           "data":{
              "id":"{USER_ID}",
              "type":"user"
           },
           "links":{
              "self":"/v2/users/{USER_ID}"
           }
        },
        "auth-client":{
           "data":{
              "id":"{AUTH-CLIENT_ID}",
              "type":"auth-client"
           },
           "links":{
              "self":"/v2/tenantns/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
           }
        }
     },
    "links":{
      "self":"/v2/workspace/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}"
    }
  },
   "meta":{}
}

This resource allows you to create an Auth Secret. If related Auth Client has type oauth2 then credentials object must contain only properties access_token, refresh_token and expires_in, otherwise if the type is other, then you can put in credentials any data that you want.

HTTP Request

POST https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets

Authorization

This request is authorized for the Workspace’s scope members with the workspaces.auth_secret.create permission.

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	yes	Workspace ID

Body Parameters

Parameter	Required	Description
type	yes	Allowed value: `auth-secret`
attributes.name	yes	Auth Secret name
attributes.state	yes	Auth Secret type. May be any of: `ready`, `error`
attributes.error	no	Auth Secret error
attributes.credentials	yes	Auth Secret credentials
attributes.credentials.access_token	yes (if `auth-client` is `oauth2`)	Auth Secret access token
attributes.credentials.refresh_token	yes (if `auth-client` is `oauth2`)	Auth Secret refresh token
attributes.credentials.expires_in	yes (if `auth-client` is `oauth2`)	Auth Secret expires in
relationships.auth_client.data.type	yes	Allowed value: `auth-client`
relationships.auth_client.data.id	yes	Auth Client ID

Returns

Returns the created Auth Secret object.

Refresh the Auth Secret

Example Request:

curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}/refresh \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json'

Example Response:

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

{
  "data": [
    {
      "id": "{AUTH-SECRET_ID}",
      "type": "auth-secret",
      "attributes": {
        "name": "Auth secret",
        "state": "ready",
        "credentials": {
          "access_token": "{ACCESS_TOKEN}",
          "refresh_token": "{REFRESH_TOKEN}",
          "expires_in": "{EXPIRES_IN}"
        }
      },
      "relationships": {
        "workspace": {
          "data": {
            "id": "{WORKSPACE_ID}",
            "type": "workspace"
          },
          "links": {
            "self": "/v2/workspace/{WORKSPACE_ID}"
          }
        },
        "user": {
          "data": {
            "id": "{USER_ID}",
            "type": "user"
          },
          "links": {
            "self": "/v2/users/{USER_ID}"
          }
        },
        "auth-client": {
          "data": {
            "id": "{AUTH-CLIENT_ID}",
            "type": "auth-client"
          },
          "links": {
            "self": "/v2/tenantns/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
          }
        }
      },
      "links": {
        "self": "/v2/workspace/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}"
      }
    }
  ],
  "meta": {}
}

This resource allows you to manually refresh the Auth Secret if it supports this operation.

HTTP Request

POST https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}/refresh

Authorization

This request is authorized for the Workspace’s scope members with the workspaces.auth_secret.refresh permission.

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	yes	Workspace ID
AUTH-SECRET_ID	yes	Auth Secret ID

Returns

Returns the Auth Secret object.

Retrieve Auth Secret by ID

Example Request:

curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID} \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": {
    "id": "{AUTH-SECRET_ID}",
    "type": "auth-secret",
    "attributes": {
      "name": "Auth secret",
      "state": "error",
      "error": "Something went technical wrong",
      "credentials": {
        "access_token": "{ACCESS_TOKEN}",
        "refresh_token": "{REFRESH_TOKEN}",
        "expires_in": "{EXPIRES_IN}"
      }
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "{WORKSPACE_ID}",
          "type": "workspace"
        },
        "links": {
          "self": "/v2/workspace/{WORKSPACE_ID}"
        }
      },
      "user": {
        "data": {
          "id": "{USER_ID}",
          "type": "user"
        },
        "links": {
          "self": "/v2/users/{USER_ID}"
        }
      },
      "auth-client": {
        "data": {
          "id": "{AUTH-CLIENT_ID}",
          "type": "auth-client"
        },
        "links": {
          "self": "/v2/tenantns/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
        }
      }
    },
    "links": {
      "self": "/v2/workspace/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}"
    }
  },
  "meta": {}
}

This resource allows you to retrieve the Auth-secret by its identifier. If the Auth-secret with given ID does not belong to the current Workspace, an error will be returned.

HTTP Request

GET https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}

Authorization

This request is authorized for the workspace’s scope members with the workspaces.auth_secret.get permission.

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	yes	Workspace ID
AUTH-SECRET_ID	yes	Auth Secret ID

Returns

Auth Secret with the given ID

Update the Auth Secret

Example Request:

curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID} \
   -X PATCH \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
    {
      "data": {
        "id": "{AUTH-SECRET_ID}",
        "type": "auth-secret",
        "attributes": {
          "name": "Auth secret",
          "state": "error",
          "error": "Something went technical wrong",
          "credentials": {
            "access_token": "{ACCESS_TOKEN}",
            "refresh_token": "{REFRESH_TOKEN}",
            "expires_in": "{EXPIRES_IN}"
          }
        },
        "auth-client": {
          "data": {
            "id": "{AUTH-CLIENT_ID}",
            "type": "auth-client"
          }
        }
      }
    }'

Example Response:

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

{
  "data": {
    "id": "{AUTH-SECRET_ID}",
    "type": "auth-secret",
    "attributes": {
      "name": "Auth secret",
      "state": "error",
      "error": "Something went technical wrong",
      "credentials": {
        "access_token": "{ACCESS_TOKEN}",
        "refresh_token": "{REFRESH_TOKEN}",
        "expires_in": "{EXPIRES_IN}"
      }
    },
    "relationships": {
      "workspace": {
        "data": {
          "id": "{WORKSPACE_ID}",
          "type": "workspace"
        },
        "links": {
          "self": "/v2/workspace/{WORKSPACE_ID}"
        }
      },
      "user": {
        "data": {
          "id": "{USER_ID}",
          "type": "user"
        },
        "links": {
          "self": "/v2/users/{USER_ID}"
        }
      },
      "auth-client": {
        "data": {
          "id": "{AUTH-CLIENT_ID}",
          "type": "auth-client"
        },
        "links": {
          "self": "/v2/tenantns/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}"
        }
      }
    },
    "links": {
      "self": "/v2/workspace/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}"
    }
  },
  "meta": {}
}

This resource allows you to update the Auth Secret. If related Auth-client has type oauth2 then credentials object must contain only properties access_token, refresh_token, expires_in, otherwise if the type is other, then you can put in credentials any data that you want.

HTTP Request

PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/auth-clients/{AUTH-CLIENT_ID}

Authorization

This request is authorized for the Workspace’s scope members with the workspaces.auth_secret.edit permission.

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	yes	Workspace ID
AUTH-SECRET_ID	yes	Auth Secret ID

Body Parameters

Parameter	Required	Description
type	yes	Allowed value: `auth-secret`
attributes.name	no	New name of the Auth Secret
attributes.credentials	no	Auth Secret credentials
relationships.auth_client.data.id	no	Auth Client ID

Returns

Returns the updated Auth-secret object.

Delete Auth Secret

Example Request:

curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID} \
   -X DELETE \
   -u {EMAIL}:{APIKEY}

This resource allows you to delete the Auth Secret.

HTTP Request

DELETE {{ api_base_url }/v2/workspaces/{WORKSPACE_ID}/secrets/{AUTH-SECRET_ID}

Authorization

This request is authorized for the Workspace’s scope members with the workspaces.auth_secret.delete permission.

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	yes	Workspace ID
AUTH-SECRET_ID	yes	Auth Secret ID

Example Response:

HTTP/1.1 204 No Content

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 – the Component can be used by the other clients in the same Tenant.
global – a special mode for Components from the standard Component set of the Platform (e.g. Timer, Webhook etc). Any Platform user can use global components.

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

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 the Platform (e.g. Timer, Webhook etc). Any user of the platform can use global components.

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":"Jane",
        "last_name":"Doe",
        "roles":[
          "admin"
        ],
        "email":"jane.doe@example.com"
      },
      "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@example.com"
      },
      "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@example.com"
      },
      "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@example.com"
      },
      "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@example.com",
                "roles": [
                  "admin"
                ]
            }
        },
        {
            "id": "5b83c0462e7785501158b654",
            "type": "contract-invite",
            "attributes": {
                "email": "member@example.com",
                "roles": [
                  "member"
                ]
            }
        },
        {
            "id": "5b855b333a667d5510ce4465",
            "type": "contract-invite",
            "attributes": {
                "email": "member@example.com",
                "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@example.com",
               "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@example.com",
      "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 an contract-invite object if the request was successful.

Returns 409 if Contract has no members and attributes.roles doesn’t contain owner role.

Update an invitation to the Contract’s scope

Example Request:

curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}/invites/{INVITE_ID} \
    -X PATCH \
    -u {EMAIL}:{APIKEY} \
    -H 'Content-Type: application/json' -d '
   {
       "data": {
           "id": "5c20bd0376b463001053a6b5",
           "type": "contract-invite",
           "attributes": {
               "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@example.com",
      "roles":[
        "owner"
      ],
      "workspace_id":"{WORKSPACE_ID}",
      "workspace_roles":[
        "integrator"
      ]
    }
  },
  "meta":{}
}

This endpoint allows to modify an existing Contract invitation.

HTTP Request

PATCH https://api.elastic.io/v2/contracts/{CONTRACT_ID}/invites/{INVITE_ID}

Authorization

URL Parameters

Parameter	Description
CONTRACT_ID	The ID of the Contract
INVITE_ID	The ID of the Contract invitation

Payload Parameters

Parameter	Required	Description
id	yes	Invitation ID. Should be the same as specified in the `INVITE_ID` URL parameter.
type	yes	A value should be “contract-invite”.
attributes.roles[]	no	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 an contract-invite object if the request was successful.

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}&filter[component]={COMPONENT_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.

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.

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"
          }
        ]
      },
      "nodes_config": {
        "step_1": {
          "passthrough": {
            "disabled": true
          }
        },
        "step_2": {
          "prefetch": 3
        }
      }
    },
    "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"
          }
        ]
      },
      "nodes_config": {
        "step_1": {
          "passthrough": {
            "disabled": true
          }
        },
        "step_2": {
          "prefetch": 3
        }
      },
      "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)
attributes.nodes_config.{STEP_ID}.prefetch	no	This parameter configures the maximum amount of messages, that the step can process simultaneously. Must be integer
attributes.nodes_config.{STEP_ID}.passthrough.disabled	no	This parameter toggles passthrough for a step. May be any of: `true`, `false`
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",
              "nodes_config": {
                "step_1": {
                  "passthrough": {
                    "disabled": true
                  }
                },
                "step_2": {
                  "prefetch": 3
                }
              }
            }
          }
    }'

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"
              }
            }
          }
        ]
      },
      "nodes_config": {
        "step_1": {
          "passthrough": {
            "disabled": true
          }
        },
        "step_2": {
          "prefetch": 3
        }
      }
    },
    "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
attributes.nodes_config.{STEP_ID}.prefetch	no	This parameter configures the maximum amount of messages, that the step can process simultaneously. Must be integer
attributes.nodes_config.{STEP_ID}.passthrough.disabled	no	This parameter toggles passthrough for a step. May be any of: `true`, `false`

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

Logs (Experimental)

Retrieve all Workspace logs

Example Request:

curl https://api.elastic.io/v2/logs?workspace_id={WORKSPACE_ID}&from=2020-01-01T00:00:00.000Z&to=2021-12-31T23:59:59.999Z&levels[]=30 \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "total":1,
  "hits":[
    {
      "id":"4eae4f60-3c53-11ea-877e-42010a1c0003",
      "workspace_id":"5cf649c3449c1e001200c1ba",
      "flow_id":"5d3848406af31c0015c2300c",
      "user_id":"5bbf202b37f655001383e923",
      "component_id":"55bb6a58fa35a40c00000009",
      "container_id": "a6dd831f-2e1f-4a4b-818d-9cc5c156d766",
      "step_id":"step_1",
      "exec_id":"31768cc6d3c64efbaf1a703392c468c1",
      "method":"timer",
      "api_username":"task-5d3848406af31c0015c2300c",
      "component_name":"Timer",
      "timestamp":"2020-01-13T10:35:42.049Z",
      "level": 30,
      "message":"Successfully downloaded and extracted slug file"
    }
  ]
}

This endpoint allows you to retrieve all logs from specified Workspace.

HTTP Request

GET https://api.elastic.io/v2/logs?workspace_id={WORKSPACE_ID}

URL Query Parameters

Parameter	Required	Description
workspace_id	Yes	Workspace identifier
flow_ids[]	No	Flow identifier
from	No	Start Date of the period. Format – ISO 8601. Example: `2020-01-12T14:50:42.215Z`
to	No	End Date of the period. Format – ISO 8601. Example: `2020-01-14T15:00:45.000Z`
search	No	String to search in logs (searching string is wrapped by tag)
offset	No	Number of items to skip from the beginning (defaults to 0)
limit	No	Number of items to return (defaults to 100)
levels[]	No	The logs level (1 - None, 10 - trace, 20 - debug, 30 - info, 40 - warn, 50 - error, 60 - fatal)

Log level None means default log level when it’s not passed.

Authorization

This request is authorized for a user with the workspaces.logs.read_all permission.

Returns

All logs from specified Workspace.

Pub/Sub Topics

What is a Topic unit?

The Topic is a JSON schema to be used to communicate publisher and many subscribers.

Create a Topic

Example Request:

 curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
  "data":{
    "type":"topic",
    "attributes":{
      "name":"Person",
      "schema":{
        "$id":"https://example.com/person.schema.json",
        "title":"Person",
        "type":"object",
        "properties":{
          "firstName":{
            "type":"string",
            "description":"The person first name."
          },
          "lastName":{
            "type":"string",
            "description":"The person last name."
          },
          "age":{
            "description":"Age in years which must be equal to or greater than zero.",
            "type":"number",
            "minimum":0
          }
        }
      }
    }
  }
}'

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data":{
    "id":"5eb15952155c920013046788",
    "type":"topic",
    "links":{
      "self":"/v2/topics/5eb15952155c920013046788"
    },
    "attributes":{
      "name":"Person",
      "schema":{
        "$id":"https://example.com/person.schema.json",
        "title":"Person",
        "type":"object",
        "properties":{
          "firstName":{
            "type":"string",
            "description":"The person first name."
          },
          "lastName":{
            "type":"string",
            "description":"The person last name."
          },
          "age":{
            "description":"Age in years which must be equal to or greater than zero.",
            "type":"number",
            "minimum":0
          }
        }
      }
    },
    "relationships":{
      "workspace":{
        "data":{
          "id":"5bbf1f5337f655001383e921",
          "type":"workspace"
        },
        "links":{
          "self":"/v2/workspaces/5bbf1f5337f655001383e921"
        }
      },
      "user":{
        "data":{
          "id":"5bbf202b37f655001383e923",
          "type":"user"
        },
        "links":{
          "self":"/v2/users/5bbf202b37f655001383e923"
        }
      }
    }
  },
  "meta":{},
  "links":{
    "self":"/v2/workspace/5bbf1f5337f655001383e921/topic/5eb15952155c920013046788"
  }
}

This endpoint allows creating a Topic only by the User that is a member of the Workspace’s scope.

HTTP Request

POST https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics

Authorization

This request is authorized for the workspace’s scope members with the workspaces.topic.create permission.

Body Parameters

Parameter	Required	Description
data.type	yes	Allowed value: “topic”
data.attributes.name	yes	Name of the Topic
data.attributes.schema	yes	A JSON schema

URL Parameters

Parameter	Description
WORKSPACE_ID	Workspace ID

Returns

Returns Topic object if the call succeeded.

Retrieve Topic by ID

Example Request:

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

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data":{
    "id":"5eb15952155c920013046788",
    "type":"topic",
    "links":{
      "self":"/v2/topics/5eb15952155c920013046788"
    },
    "attributes":{
      "name":"Person",
      "schema":{
        "$id":"https://example.com/person.schema.json",
        "title":"Person",
        "type":"object",
        "properties":{
          "firstName":{
            "type":"string",
            "description":"The person first name."
          },
          "lastName":{
            "type":"string",
            "description":"The person last name."
          },
          "age":{
            "description":"Age in years which must be equal to or greater than zero.",
            "type":"number",
            "minimum":0
          }
        }
      }
    },
    "relationships":{
      "workspace":{
        "data":{
          "id":"5bbf1f5337f655001383e921",
          "type":"workspace"
        },
        "links":{
          "self":"/v2/workspaces/5bbf1f5337f655001383e921"
        }
      },
      "user":{
        "data":{
          "id":"5bbf202b37f655001383e923",
          "type":"user"
        },
        "links":{
          "self":"/v2/users/5bbf202b37f655001383e923"
        }
      }
    }
  },
  "meta":{},
  "links":{
    "self":"/v2/workspace/5bbf1f5337f655001383e921/topic/5eb15952155c920013046788"
  }
}

This endpoint allows retrieve one Topic by ID.

HTTP Request

GET https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics/{TOPIC_ID}

Authorization

This request is authorized for the workspace’s scope members with the workspaces.topic.get permission.

URL Parameters

Parameter	Description
WORKSPACE_ID	Workspace ID
TOPIC_ID	Topic ID

Returns

Returns Topic object if the call succeeded

Retrieve all Topics

Example Request:

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

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data":[
    {
      "id":"5eb15952155c920013046788",
      "type":"topic",
      "links":{
        "self":"/v2/topics/5eb15952155c920013046788"
      },
      "attributes":{
        "name":"Person",
        "schema":{
          "$id":"https://example.com/person.schema.json",
          "title":"Person",
          "type":"object",
          "properties":{
            "firstName":{
              "type":"string",
              "description":"The person first name."
            },
            "lastName":{
              "type":"string",
              "description":"The person last name."
            },
            "age":{
              "description":"Age in years which must be equal to or greater than zero.",
              "type":"number",
              "minimum":0
            }
          }
        }
      },
      "relationships":{
        "workspace":{
          "data":{
            "id":"5bbf1f5337f655001383e921",
            "type":"workspace"
          },
          "links":{
            "self":"/v2/workspaces/5bbf1f5337f655001383e921"
          }
        },
        "user":{
          "data":{
            "id":"5bbf202b37f655001383e923",
            "type":"user"
          },
          "links":{
            "self":"/v2/users/5bbf202b37f655001383e923"
          }
        }
      }
    }
  ],
  "meta":{}
}

This endpoint allows to retrieve all Topics.

HTTP Request

GET https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics

Authorization

This request is authorized for the workspace’s scope members with the workspaces.topic.get permission.

URL Parameters

Parameter	Description
WORKSPACE_ID	Workspace ID

Returns

Returns an array of Topics if the call succeeded.

Update a Topic

Example Request:

 curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics/{TOPIC_ID} \
   -X PATCH \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
  "data":{
    "id": "{TOPIC_ID}"
    "type":"topic",
    "attributes":{
      "name":"Person",
      "schema":{
        "$id":"https://example.com/person.schema.json",
        "title":"Person",
        "type":"object",
        "properties":{
          "firstName":{
            "type":"string",
            "description":"The person first name."
          },
          "lastName":{
            "type":"string",
            "description":"The person last name."
          },
          "middleName":{
            "type":"string",
            "description":"The person middle name."
          },
          "age":{
            "description":"Age in years which must be equal to or greater than zero.",
            "type":"number",
            "minimum":0
          }
        }
      }
    }
  }
}'

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data":{
    "id":"5eb15952155c920013046788",
    "type":"topic",
    "links":{
      "self":"/v2/topics/5eb15952155c920013046788"
    },
    "attributes":{
      "name":"Person",
      "schema":{
        "$id":"https://example.com/person.schema.json",
        "title":"Person",
        "type":"object",
        "properties":{
          "firstName":{
            "type":"string",
            "description":"The person first name."
          },
          "lastName":{
            "type":"string",
            "description":"The person last name."
          },
          "middleName":{
            "type":"string",
            "description":"The person middle name."
          },
          "age":{
            "description":"Age in years which must be equal to or greater than zero.",
            "type":"number",
            "minimum":0
          }
        }
      }
    },
    "relationships":{
      "workspace":{
        "data":{
          "id":"5bbf1f5337f655001383e921",
          "type":"workspace"
        },
        "links":{
          "self":"/v2/workspaces/5bbf1f5337f655001383e921"
        }
      },
      "user":{
        "data":{
          "id":"5bbf202b37f655001383e923",
          "type":"user"
        },
        "links":{
          "self":"/v2/users/5bbf202b37f655001383e923"
        }
      }
    }
  },
  "meta":{},
  "links":{
    "self":"/v2/workspace/5bbf1f5337f655001383e921/topic/5eb15952155c920013046788"
  }
}

This endpoint allows updating a Topic only by the User that is a member of the Workspace’s scope.

HTTP Request

PATCH https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics/{TOPIC_ID}

Authorization

This request is authorized for the workspace’s scope members with the workspaces.topic.edit permission.

Body Parameters

Parameter	Required	Description
data.type	yes	Allowed value: “topic”
data.id	yes	Topic ID
data.attributes.name	no	Name of the Topic
data.attributes.schema	no	A JSON schema

URL Parameters

Parameter	Description
WORKSPACE_ID	The ID of the Workspace
TOPIC_ID	The ID of the Topic

Returns

Returns Topic object if the call succeeded

Delete a Topic

Example Request:

 curl https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics/{TOPIC_ID} \
   -X DELETE \
   -u {EMAIL}:{APIKEY} \

Example Response:

HTTP/1.1 204 No Content

This endpoint allows deleting a Topic.

HTTP Request

DELETE https://api.elastic.io/v2/workspaces/{WORKSPACE_ID}/topics/{TOPIC_ID}

Authorization

This request is authorized for the workspace’s scope members with the workspaces.topic.delete permission.

URL Parameters

Parameter	Description
WORKSPACE_ID	Workspace ID
TOPIC_ID	Topic ID

Returns

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

Quota Usages

Retrieve a contract usage metrics by ID

Example Request:

curl https://api.elastic.io/v2/quota-usages/contracts/{CONTRACT_ID}?from=yyyy-mm-dd&to=yyyy-mm-dd \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": {
    "memory": 2245348201,
    "cpu": 768877946
  }
}

This endpoint allows you to retrieve a contract usage metrics by its ID. Memory usage is reported as a sum of RAM usage for each second during the specified period for each step. CPU usage is reported as an amount of consumed CPU for each step.

HTTP Request

GET https://api.elastic.io/v2/quota-usages/contracts/{CONTRACT_ID}?from={DATE_FROM}&to={DATE_TO}

URL Parameters

Parameter	Required	Description
CONTRACT_ID	Yes	Contract identifier
FROM	Yes	Start Date of the period (inclusive). Format – ISO 8601
TO	Yes	End Date of the period (inclusive). Format – ISO 8601

Authorization

Only a corresponding contract member can be authorized to send this request.

Returns

Memory (in MiB) and CPU (in milli CPU) usage for the given Contract ID

Retrieve a usage history for a contract

Example Request:

curl https://api.elastic.io/v2/quota-usages/contracts/{CONTRACT_ID}/history?from=yyyy-mm-dd&to=yyyy-mm-dd \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": [
    {
      "id": "2019-09-01",
      "memory": 3013817361,
      "cpu": 1033025938
    },
    {
      "id": "2019-09-02",
      "memory": 1175586955,
      "cpu": 1228829840
    },
    {
      "id": "2019-09-03",
      "memory": 1415099916,
      "cpu": 914085387
    },
    {
      "id": "2019-09-04",
      "memory": 4333364932,
      "cpu": 905498466
    },
    {
      "id": "2019-09-05",
      "memory": 3103767554,
      "cpu": 1435640133
    },
    {
      "id": "2019-09-06",
      "memory": 4438218529,
      "cpu": 1312683914
    },
    {
      "id": "2019-09-07",
      "memory": 3115617368,
      "cpu": 1273318310
    },
    {
      "id": "2019-09-08",
      "memory": 2555583930,
      "cpu": 425826260
    },
    {
      "id": "2019-09-09",
      "memory": 1300915290,
      "cpu": 578666524
    },
    {
      "id": "2019-09-10",
      "memory": 2578000474,
      "cpu": 1200524984
    },
    {
      "id": "2019-09-11",
      "memory": 1244645541,
      "cpu": 1430851170
    },
    {
      "id": "2019-09-12",
      "memory": 3153146274,
      "cpu": 766348575
    },
    {
      "id": "2019-09-13",
      "memory": 4331061352,
      "cpu": 1524287794
    },
    {
      "id": "2019-09-14",
      "memory": 3449265869,
      "cpu": 724878805
    },
    {
      "id": "2019-09-15",
      "memory": 4380354401,
      "cpu": 681580868
    },
    {
      "id": "2019-09-16",
      "memory": 4195723875,
      "cpu": 1378873383
    },
    {
      "id": "2019-09-17",
      "memory": 2588792850,
      "cpu": 409637208
    },
    {
      "id": "2019-09-18",
      "memory": 2845001570,
      "cpu": 790312916
    },
    {
      "id": "2019-09-19",
      "memory": 3177605905,
      "cpu": 976102838
    },
    {
      "id": "2019-09-20",
      "memory": 1577592652,
      "cpu": 1237769441
    },
    {
      "id": "2019-09-21",
      "memory": 3538891088,
      "cpu": 890528854
    },
    {
      "id": "2019-09-22",
      "memory": 2186125801,
      "cpu": 605849778
    },
    {
      "id": "2019-09-23",
      "memory": 1560495801,
      "cpu": 924019694
    },
    {
      "id": "2019-09-24",
      "memory": 1457907045,
      "cpu": 935557170
    },
    {
      "id": "2019-09-25",
      "memory": 1353442520,
      "cpu": 1262766351
    },
    {
      "id": "2019-09-26",
      "memory": 3685608278,
      "cpu": 1502041477
    },
    {
      "id": "2019-09-27",
      "memory": 2866504778,
      "cpu": 1420758756
    },
    {
      "id": "2019-09-28",
      "memory": 3279678917,
      "cpu": 1458025964
    },
    {
      "id": "2019-09-29",
      "memory": 2408913650,
      "cpu": 1405853054
    },
    {
      "id": "2019-09-30",
      "memory": 3934495260,
      "cpu": 828444175
    }
  ]
}

This endpoint allows you to retrieve a usage history for certain Contract. id – is a date of the day. memory – is a memory usage, reported as a sum of RAM usage for a day. In MiB. cpu – is CPU usage, reported as an amount of consumed CPU for a day. In milli CPU.

HTTP Request

GET https://api.elastic.io/v2/quota-usages/contracts/{CONTRACT_ID}/history?from={DATE_FROM}&to={DATE_TO}&group_by={GROUP_BY}

URL Parameters

Parameter	Required	Description
CONTRACT_ID	Yes	Contract identifier
FROM	Yes	Start Date of the period (inclusive). Format – ISO 8601
TO	Yes	End Date of the period (inclusive). Format – ISO 8601
GROUP_BY	No	Param to specify aggregation period. Format - ‘day’, 'month’

Authorization

Only for contract members.

Returns

Array of contract usages within specified period.

Retrieve a workspace usage metrics by ID

Example Request:

curl https://api.elastic.io/v2/quota-usages/workspaces/{WORKSPACE_ID}?from=yyyy-mm-dd&to=yyyy-mm-dd \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": {
    "memory": 2245348201,
    "cpu": 768877946,
    "flows": 12
  }
}

This endpoint allows you to retrieve the usage metrics for a workspace by its ID. Memory usage is reported as a sum of RAM usage for each second during the specified period for each step. CPU usage is reported as an amount of consumed CPU resource for each step.

HTTP Request

GET https://api.elastic.io/v2/quota-usages/workspaces/{WORKSPACE_ID}?from={DATE_FROM}&to={DATE_TO}

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	Yes	Workspace identifier
FROM	Yes	Start Date of the period (inclusive). Format – ISO 8601
TO	Yes	End Date of the period (inclusive). Format – ISO 8601

Authorization

Only a corresponding contract member can be authorized to send this request.

Returns

Memory (in MiB) and CPU (in milli CPU) usage with a number of unique flows for the given Workspace ID

Retrieve a usage history for a workspace

Example Request:

curl https://api.elastic.io/v2/quota-usages/workspace/{WORKSPACE_ID}/history?from=2019-09-01&to=2019-10-01 \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": [
    {
      "id": "2019-09-01",
      "memory": 128964526,
      "cpu": 114306500
    },
    {
      "id": "2019-09-02",
      "memory": 408936660,
      "cpu": 79852852
    },
    {
      "id": "2019-09-03",
      "memory": 386725520,
      "cpu": 125872319
    },
    {
      "id": "2019-09-04",
      "memory": 193675746,
      "cpu": 92099164
    },
    {
      "id": "2019-09-05",
      "memory": 177530397,
      "cpu": 43157955
    },
    {
      "id": "2019-09-06",
      "memory": 353733337,
      "cpu": 109371060
    },
    {
      "id": "2019-09-07",
      "memory": 144626872,
      "cpu": 85429328
    },
    {
      "id": "2019-09-08",
      "memory": 272579360,
      "cpu": 143888954
    },
    {
      "id": "2019-09-09",
      "memory": 185053387,
      "cpu": 135083221
    },
    {
      "id": "2019-09-10",
      "memory": 209892504,
      "cpu": 118582342
    },
    {
      "id": "2019-09-11",
      "memory": 290143226,
      "cpu": 55125590
    },
    {
      "id": "2019-09-12",
      "memory": 303180124,
      "cpu": 94330986
    },
    {
      "id": "2019-09-13",
      "memory": 300608414,
      "cpu": 151294431
    },
    {
      "id": "2019-09-14",
      "memory": 180244867,
      "cpu": 140865929
    },
    {
      "id": "2019-09-15",
      "memory": 187069283,
      "cpu": 109569827
    },
    {
      "id": "2019-09-16",
      "memory": 439170195,
      "cpu": 151515652
    },
    {
      "id": "2019-09-17",
      "memory": 323928269,
      "cpu": 39417483
    },
    {
      "id": "2019-09-18",
      "memory": 205336814,
      "cpu": 120806191
    },
    {
      "id": "2019-09-19",
      "memory": 310188765,
      "cpu": 110638121
    },
    {
      "id": "2019-09-20",
      "memory": 382909571,
      "cpu": 75652523
    },
    {
      "id": "2019-09-21",
      "memory": 307170731,
      "cpu": 95998011
    },
    {
      "id": "2019-09-22",
      "memory": 116159302,
      "cpu": 135483445
    },
    {
      "id": "2019-09-23",
      "memory": 141174486,
      "cpu": 127318996
    },
    {
      "id": "2019-09-24",
      "memory": 150589801,
      "cpu": 86755184
    },
    {
      "id": "2019-09-25",
      "memory": 219903014,
      "cpu": 91103923
    },
    {
      "id": "2019-09-26",
      "memory": 140599462,
      "cpu": 47526413
    },
    {
      "id": "2019-09-27",
      "memory": 183323584,
      "cpu": 80036178
    },
    {
      "id": "2019-09-28",
      "memory": 230017864,
      "cpu": 133791324
    },
    {
      "id": "2019-09-29",
      "memory": 171331176,
      "cpu": 66413876
    },
    {
      "id": "2019-09-30",
      "memory": 289801698,
      "cpu": 95146346
    }
  ]
}

This endpoint allows you to retrieve a usage history for certain Workspace. id – is a date of the day. memory – is a memory usage, reported as a sum of RAM usage for a day. In MiB. cpu – is CPU usage, reported as an amount of consumed CPU for a day. In milli CPU.

HTTP Request

GET https://api.elastic.io/v2/quota-usages/workspaces/{WORKSPACE_ID}/history?from={DATE_FROM}&to={DATE_TO}&group_by={GROUP_BY}

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	Yes	Workspace identifier
FROM	Yes	Start Date of the period (inclusive). Format – ISO 8601
TO	Yes	End Date of the period (inclusive). Format – ISO 8601
GROUP_BY	No	Param to specify aggregation period. Format - 'day’, 'month’

Authorization

For Workspace members or for members of the corresponding Contract with the permission contracts.workspace.listAll.

Returns

Array of workspace usages within specified period.

Retrieve a workspace usage metrics per flows

Example Request:

curl https://api.elastic.io/v2/quota-usages/workspaces/{WORKSPACE_ID}/flows?from=yyyy-mm-dd&to=yyyy-mm-dd \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
   "data": [
        {
            "memory": 20489,
            "cpu": 3270,
            "id": "5d820965844c7d0014501089"
        },
        {
            "memory": 20454,
            "cpu": 3119,
            "id": "5d820927844c7d0014500eea"
        },
        {
            "memory": 20296,
            "cpu": 3105,
            "id": "5d81f7265301e30014ac6912"
        },
        {
            "memory": 19695,
            "cpu": 3072,
            "id": "5d820d31074a3800138853c7"
        }
    ]
}

This endpoint allows you to retrieve the usage metrics for each flow that was active in the specified period in a certain workspace. Memory usage is reported as a sum of RAM usage for each second during the specified period for each step. CPU usage is reported as an amount of consumed CPU resource for each step.

HTTP Request

GET https://api.elastic.io/v2/quota-usages/workspaces/{WORKSPACE_ID}/flows?from={DATE_FROM}&to={DATE_TO}

URL Parameters

Parameter	Required	Description
WORKSPACE_ID	Yes	Workspace identifier
FROM	Yes	Start Date of the period (inclusive). Format – ISO 8601
TO	Yes	End Date of the period (inclusive). Format – ISO 8601

Authorization

Only a corresponding workspace member can be authorized to send this request.

Returns

Flows Id, memory (in MiB), CPU (in milli CPU) usage for the given Workspace ID

Retrieve a usage history for a flow

Example Request:

curl https://api.elastic.io/v2/quota-usages/flows/{FLOW_ID}/history?from=2019-09-01&to=2019-10-01 \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": [
    {
      "id": "2019-09-01",
      "memory": 128964526,
      "cpu": 114306500
    },
    {
      "id": "2019-09-02",
      "memory": 408936660,
      "cpu": 79852852
    },
    {
      "id": "2019-09-03",
      "memory": 386725520,
      "cpu": 125872319
    },
    {
      "id": "2019-09-04",
      "memory": 193675746,
      "cpu": 92099164
    },
    {
      "id": "2019-09-05",
      "memory": 177530397,
      "cpu": 43157955
    },
    {
      "id": "2019-09-06",
      "memory": 353733337,
      "cpu": 109371060
    },
    {
      "id": "2019-09-07",
      "memory": 144626872,
      "cpu": 85429328
    },
    {
      "id": "2019-09-08",
      "memory": 272579360,
      "cpu": 143888954
    },
    {
      "id": "2019-09-09",
      "memory": 185053387,
      "cpu": 135083221
    },
    {
      "id": "2019-09-10",
      "memory": 209892504,
      "cpu": 118582342
    },
    {
      "id": "2019-09-11",
      "memory": 290143226,
      "cpu": 55125590
    },
    {
      "id": "2019-09-12",
      "memory": 303180124,
      "cpu": 94330986
    },
    {
      "id": "2019-09-13",
      "memory": 300608414,
      "cpu": 151294431
    },
    {
      "id": "2019-09-14",
      "memory": 180244867,
      "cpu": 140865929
    },
    {
      "id": "2019-09-15",
      "memory": 187069283,
      "cpu": 109569827
    },
    {
      "id": "2019-09-16",
      "memory": 439170195,
      "cpu": 151515652
    },
    {
      "id": "2019-09-17",
      "memory": 323928269,
      "cpu": 39417483
    },
    {
      "id": "2019-09-18",
      "memory": 205336814,
      "cpu": 120806191
    },
    {
      "id": "2019-09-19",
      "memory": 310188765,
      "cpu": 110638121
    },
    {
      "id": "2019-09-20",
      "memory": 382909571,
      "cpu": 75652523
    },
    {
      "id": "2019-09-21",
      "memory": 307170731,
      "cpu": 95998011
    },
    {
      "id": "2019-09-22",
      "memory": 116159302,
      "cpu": 135483445
    },
    {
      "id": "2019-09-23",
      "memory": 141174486,
      "cpu": 127318996
    },
    {
      "id": "2019-09-24",
      "memory": 150589801,
      "cpu": 86755184
    },
    {
      "id": "2019-09-25",
      "memory": 219903014,
      "cpu": 91103923
    },
    {
      "id": "2019-09-26",
      "memory": 140599462,
      "cpu": 47526413
    },
    {
      "id": "2019-09-27",
      "memory": 183323584,
      "cpu": 80036178
    },
    {
      "id": "2019-09-28",
      "memory": 230017864,
      "cpu": 133791324
    },
    {
      "id": "2019-09-29",
      "memory": 171331176,
      "cpu": 66413876
    },
    {
      "id": "2019-09-30",
      "memory": 289801698,
      "cpu": 95146346
    }
  ]
}

This endpoint allows you to retrieve a usage history for certain Flow. id – is a date of the day. memory – is a memory usage, reported as a sum of RAM usage for a day. In MiB. cpu – is CPU usage, reported as an amount of consumed CPU for a day. In milli CPU.

HTTP Request

GET https://api.elastic.io/v2/quota-usages/flows/{FLOW_ID}/history?from={DATE_FROM}&to={DATE_TO}&group_by={GROUP_BY}

URL Parameters

Parameter	Required	Description
FLOW_ID	Yes	Flow identifier
FROM	Yes	Start Date of the period (inclusive). Format – ISO 8601
TO	Yes	End Date of the period (inclusive). Format – ISO 8601
GROUP_BY	No	Param to specify aggregation period. Format - 'day’, 'month’

Authorization

Only a corresponding workspace member can be authorized to send this request.

Returns

Array of flow usages within specified period.

Recipes (Experimental)

The recipe has an attribute visibility, which indicates how the recipe is shared by other clients. A shared recipe is available to other users for their Flows. There are four sharing modes:

workspace – Only Workspace members can use the recipe.
contract – Members of all Contract Workspaces can use the recipe.
tenant – Recipe is available to other clients in the tenant.
global – Any user of the platform can use these recipes.

Accordingly, a set of recipes available for each user consists of: non-shared recipes from the user’s Workspace, recipes with contract, tenant and global access. When you create a recipe, it has default visibility workspace.

Note: deleting recipes with contract, tenant and global visibility is forbidden. Note: downgrading recipes visibility is forbidden.

Create a recipe

Example Request (without required trigger/action fields):

curl -X POST https://api.elastic.io/v2/recipes \
  -u {EMAIL}:{APIKEY} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -d '
  {
    "data": {
      "type": "recipe",
      "attributes": {
        "activation_config": {
          "variables": [{
            "title": "Email to fill a \"CC\" field",
            "key": "cc"
          }],
          "credentials": [{
            "description": "Credentials to access your Petstore",
            "stepId": "step_1"
          }]
        },
        "marketplace_content": {
          "title": "My Recipe",
          "description": "# Scelerisque eleifend donec pretium vulputate sapien. \n\n ## Tincidunt id aliquet risus feugiat. \n\nA condimentum vitae sapien pellentesque habitant morbi tristique senectus et. **Nec feugiat in fermentum posuere urna**.",
          "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "help_text": "No setup required",
          "tags": []
        },
        "flow_template": {
          "cron": "*/3 * * * *",
          "graph": {
            "nodes": [
              {
                "name": "Step name",
                "description": "Step description",
                "command": "elasticio/petstore:getPetsByStatusWithGenerators@latest",
                "id": "step_1"
              },
              {
                "name": "Step name",
                "description": "Step description",
                "command": "elasticio/email:send@latest",
                "fields": {
                  "dontThrowErrorFlg": true
                },
                "id": "step_2"
              }
            ],
            "edges": [
              {
                "config": {
                  "mapper_type": "jsonata",
                  "mapper": {
                    "to": "pets[0].name",
                    "cc": "$getFlowVariables().cc",
                    "subject": "pets[0].id",
                    "textBody": "pets[0].status"
                  },
                  "condition": null
                },
                "source": "step_1",
                "target": "step_2"
              }
            ]
          }
        }
      },
      "relationships": {
        "workspace": {
          "data": {
            "type": "workspace",
            "id": "{WORKSPACE_ID}"
          }
        }
      }
    }
  }'

Example Request (with required trigger/action fields):

curl -X POST https://api.elastic.io/v2/recipes \
  -u {EMAIL}:{APIKEY} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -d '
  {
    "data": {
      "type": "recipe",
      "attributes": {
        "activation_config": {
          "variables": [{
            "title": "Email to fill a \"CC\" field",
            "key": "cc"
          }],
          "credentials": [{
            "description": "Credentials to access your Petstore",
            "stepId": "step_1"
          }]
        },
        "marketplace_content": {
          "title": "My Recipe",
          "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "help_text": "No setup required",
          "tags": []
        },
        "flow_template": {
          "cron": "*/3 * * * *",
          "graph": {
            "nodes": [
              {
                "name": "Step name",
                "description": "Step description",
                "command": "elasticio/petstore:getPetsByStatusWithGenerators@latest",
                "fields": {
                  "status": "pending"
                },
                "id": "step_1"
              },
              {
                "name": "Step name",
                "description": "Step description",
                "command": "elasticio/email:send@latest",
                "fields": {
                  "dontThrowErrorFlg": true
                },
                "id": "step_2"
              }
            ],
            "edges": [
              {
                "config": {
                  "mapper_type": "jsonata",
                  "mapper": {
                    "to": "pets[0].name",
                    "cc": "$getFlowVariables().cc",
                    "subject": "pets[0].id",
                    "textBody": "pets[0].status"
                  },
                  "condition": null
                },
                "source": "step_1",
                "target": "step_2"
              }
            ]
          }
        }
      },
      "relationships": {
        "workspace": {
          "data": {
            "type": "workspace",
            "id": "{WORKSPACE_ID}"
          }
        }
      }
    }
  }'

Example Response:

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

{
  "data": {
    "id": "{RECIPE_ID}",
    "type": "recipe",
    "links": {
      "self": "/v2/recipes/{RECIPE_ID}"
    },
    "attributes": {
      "visibility": "workspace",
      "activation_config": {
        "variables": [{
          "title": "Email to fill a \"CC\" field",
          "key": "cc"
        }],
        "credentials": [{
          "description": "Credentials to access your Petstore",
          "stepId": "step_1"
        }]
      },
      "marketplace_content": {
        "title": "My Recipe",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "help_text": "No setup required",
        "tags": []
      },
      "flow_template": {
        "cron": "*/3 * * * *",
        "graph": {
          "edges": [
            {
              "config": {
                "condition": null,
                "mapper": {
                  "textBody": "pets[0].status",
                  "subject": "pets[0].id",
                  "to": "pets[0].name",
                  "cc": "$getFlowVariables().cc"
                },
                "mapper_type": "jsonata"
              },
              "source": "step_1",
              "target": "step_2"
            }
          ],
          "nodes": [
            {
              "name": "Step name",
              "description": "Step description",
              "command": "elasticio/petstore:getPetsByStatusWithGenerators@latest",
              "id": "step_1"
            },
            {
              "name": "Step name",
              "description": "Step description",
              "command": "elasticio/email:send@latest",
              "fields": {
                "dontThrowErrorFlg": true
              },
              "id": "step_2"
            }
          ]
        }
      },
      "created_at": "2019-09-30T11:22:19.822Z",
      "updated_at": "2019-09-30T11:22:19.822Z"
    },
    "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}"
        }
      },
      "contract": {
        "data": {
          "id": "{CONTRACT_ID}",
          "type": "contract"
        },
        "links": {
          "self": "/v2/contracts/{CONTRACT_ID}"
        }
      }
    }
  },
  "meta": {}
}

This resource allows you to create a new recipe.

HTTP Request

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

Body Parameters

Parameter	Required	Description
type	yes	A value must be `recipe`
attributes.activation_config.variables	no	List of variables used by steps in a flow
attributes.activation_config.credentials	no	List of credentials used by steps in a flow
attributes.marketplace_content.name	yes	Recipe name
attributes.marketplace_content.description	yes	Recipe description
attributes.marketplace_content.short_description	yes	Recipe short description
attributes.marketplace_content.help_text	no	Recipe help text
attributes.flow_template.cron	no	Cron expression
attributes.flow_template.graph	yes	Recipe graph representing component connections
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 to only a user with workspaces.recipe.edit permission

Returns

Returns the created recipe

Note: you can use $getFlowVariables().{variable_name} only in attributes.flow_template.edges.config.mapper section. Variable value will be defined by recipe user during activation.

Create a recipe from existing flow

Example Request:

curl -X POST https://api.elastic.io/v2/flows/{FLOW_ID}/export-to-recipe \
  -u {EMAIL}:{APIKEY} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -d '
  {
    "data": {
      "type": "flow-export-to-recipe-config",
      "relationships": {
        "workspace": {
          "data": {
            "type": "workspace",
            "id": "{WORKSPACE_ID}"
          }
        }
      }
    }
  }'

Example Response:

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

{
  "data": {
    "id": "{RECIPE_ID}",
    "type": "recipe",
    "links": {
      "self": "/v2/recipes/{RECIPE_ID}"
    },
    "attributes": {
      "visibility": "workspace",
      "activation_config": {
        "credentials": [{
          "description": "",
          "stepId": "step_1"
        }]
      },
      "marketplace_content": {
        "title": "Recipe based on the flow 'My flow'",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "help_text": "Recipe based on the flow 'My flow'",
        "tags": []
      },
      "flow_template": {
        "cron": "*/3 * * * *",
        "graph": {
          "edges": [
            {
              "config": {
                "condition": null,
                "mapper": {
                  "textBody": "pets[0].status",
                  "subject": "pets[0].id",
                  "to": "pets[0].name",
                  "cc": "cc"
                },
                "mapper_type": "jsonata"
              },
              "source": "step_1",
              "target": "step_2"
            }
          ],
          "nodes": [
            {
              "name": "Step name",
              "description": "Step description",
              "command": "elasticio/petstore:getPetsByStatusWithGenerators@1eb65b1721c45e746c25d64e3ab85888f18f31c5",
              "id": "step_1"
            },
            {
              "name": "Step name",
              "description": "Step description",
              "command": "elasticio/email:send@3746623b98821a291fb1e132f1278978c5f98f9b",
              "fields": {
                "dontThrowErrorFlg": true
              },
              "id": "step_2"
            }
          ]
        }
      },
      "created_at": "2019-09-30T11:22:19.822Z",
      "updated_at": "2019-09-30T11:22:19.822Z"
    },
    "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}"
        }
      },
      "contract": {
        "data": {
          "id": "{CONTRACT_ID}",
          "type": "contract"
        },
        "links": {
          "self": "/v2/contracts/{CONTRACT_ID}"
        }
      }
    }
  },
  "meta": {}
}

This resource allows you to export an existing flow as a new recipe.

HTTP Request

POST https://api.elastic.io/v2/flows/{FLOW_ID}/export-to-recipe

Body Parameters

Parameter	Required	Description
type	yes	A value must be `flow-export-to-recipe-config`
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 to only a user with workspaces.recipe.edit permission

Returns

Returns the created recipe

Retrieve a recipe by ID

Example Request:

curl https://api.elastic.io/v2/recipes/{RECIPE_ID} \
   -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": {
    "id": "{RECIPE_ID}",
    "type": "recipe",
    "links": {
      "self": "/v2/recipes/{RECIPE_ID}"
    },
    "attributes": {
      "visibility": "workspace",
      "activation_config": {
        "variables": [{
          "title": "Email to fill a \"CC\" field",
          "key": "cc"
        }],
        "credentials": [{
          "description": "Credentials to access your Petstore",
          "stepId": "step_1"
        }]
      },
      "marketplace_content": {
        "title": "My Recipe",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "help_text": "No setup required",
        "tags": []
      },
      "flow_template": {
        "graph": {
          "edges": [
            {
              "config": {
                "mapper_type": "jsonata",
                "mapper": {
                  "to": "pets[0].name",
                  "subject": "pets[0].id",
                  "textBody": "pets[0].status",
                  "cc": "$getFlowVariables().cc"
                },
                "condition": null
              },
              "source": "step_1",
              "target": "step_2"
            }
          ],
          "nodes": [
            {
              "command": "elasticio/petstore:getPetsByStatusWithGenerators@latest",
              "id": "step_1"
            },
            {
              "command": "elasticio/email:send@latest",
              "fields": {
                "dontThrowErrorFlg": true
              },
              "id": "step_2"
            }
          ]
        }
      },
      "created_at": "2019-09-29T11:22:19.822Z",
      "updated_at": "2019-09-30T11:22:19.822Z"
    },
    "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}"
        }
      },
      "contract": {
        "data": {
          "id": "{CONTRACT_ID}",
          "type": "contract"
        },
        "links": {
          "self": "/v2/contracts/{CONTRACT_ID}"
        }
      }
    }
  },
  "meta": {}
}

This resource allows you to retrieve a recipe by its ID.

HTTP Request

GET https://api.elastic.io/v2/recipes/{RECIPE_ID}

URL Parameters

Parameter	Required	Description
RECIPE_ID	Yes	Recipe identifier

Authorization

This request is authorized to a member of the corresponding contract only.

Returns

The recipe with given ID

Retrieve all recipes

Example Request (with custom paging):

curl 'https://api.elastic.io/v2/recipes?workspace_id={WORKSPACE_ID}&page[size]=2&page[number]=1' \
   -g -u {EMAIL}:{APIKEY}

Example Response:

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

{
  "data": [
    {
      "id": "{RECIPE_ID}",
      "type": "recipe",
      "links": {
        "self": "/v2/recipes/{RECIPE_ID}"
      },
      "attributes": {
        "visibility": "workspace",
        "activation_config": {
          "variables": [
            {
              "title": "Email to fill a \"CC\" field",
              "key": "cc"
            }
          ],
          "credentials": [
            {
              "description": "Credentials to access your Petstore",
              "stepId": "step_1"
            }
          ]
        },
        "marketplace_content": {
          "title": "My first recipe",
          "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "help_text": "No setup required",
          "tags": []
        },
        "flow_template": {
          "graph": {
            "edges": [
              {
                "config": {
                  "mapper_type": "jsonata",
                  "mapper": {
                    "to": "pets[0].name",
                    "cc": "$getFlowVariables()..cc",
                    "subject": "pets[0].id",
                    "textBody": "pets[0].status"
                  },
                  "condition": null
                },
                "source": "step_1",
                "target": "step_2"
              }
            ],
            "nodes": [
              {
                "command": "elasticio/petstore:getPetsByStatusWithGenerators@7edfbaba2e7457b7d4413dcbfd9e4fa7991c0a1a",
                "fields": {
                  "status": "pending"
                },
                "id": "step_1"
              },
              {
                "command": "elasticio/email:send@b9f4e1483c964e0c2fe6f7600ffe81b6aca8ef33",
                "fields": {
                  "dontThrowErrorFlg": true
                },
                "id": "step_2"
              }
            ]
          }
        },
        "created_at": "2019-09-29T11:22:19.822Z",
        "updated_at": "2019-09-29T11:22:19.822Z"
      },
      "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}"
          }
        },
        "contract": {
          "data": {
            "id": "{CONTRACT_ID}",
            "type": "contract"
          },
          "links": {
            "self": "/v2/contracts/{CONTRACT_ID}"
          }
        }
      }
    },
    {
      "id": "{RECIPE_ID}",
      "type": "recipe",
      "links": {
        "self": "/v2/recipes/{RECIPE_ID}"
      },
      "attributes": {
        "visibility": "workspace",
        "activation_config": {
          "variables": [
            {
              "title": "Email to fill a \"CC\" field",
              "key": "cc"
            }
          ],
          "credentials": [
            {
              "description": "Credentials to access your Petstore",
              "stepId": "step_1"
            }
          ]
        },
        "marketplace_content": {
          "title": "My second recipe",
          "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
          "help_text": "No setup required",
          "tags": []
        },
        "flow_template": {
          "graph": {
            "edges": [
              {
                "config": {
                  "mapper_type": "jsonata",
                  "mapper": {
                    "to": "pets[0].name",
                    "cc": "$getFlowVariables().cc",
                    "subject": "pets[0].id",
                    "textBody": "pets[0].status"
                  },
                  "condition": null
                },
                "source": "step_1",
                "target": "step_2"
              }
            ],
            "nodes": [
              {
                "command": "elasticio/petstore:getPetsByStatusWithGenerators@7edfbaba2e7457b7d4413dcbfd9e4fa7991c0a1a",
                "fields": {
                  "status": "pending"
                },
                "id": "step_1"
              },
              {
                "command": "elasticio/email:send@b9f4e1483c964e0c2fe6f7600ffe81b6aca8ef33",
                "fields": {
                  "dontThrowErrorFlg": true
                },
                "id": "step_2"
              }
            ]
          }
        },
        "created_at": "2019-09-30T11:22:19.822Z",
        "updated_at": "2019-09-30T11:22:19.822Z"
      },
      "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}"
          }
        },
        "contract": {
          "data": {
            "id": "{CONTRACT_ID}",
            "type": "contract"
          },
          "links": {
            "self": "/v2/contracts/{CONTRACT_ID}"
          }
        }
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 2,
    "total": 16,
    "total_pages": 8
  }
}

This resource allows you to retrieve all recipes.

HTTP Request

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

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

Returns

Returns all recipes which are available in the specified Workspace.

Update a recipe

Example request

curl https://api.elastic.io/v2/recipes/{RECIPE_ID} \
  -X PATCH \
  -u {EMAIL}:{APIKEY} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -d '
   {
     "data": {
       "id": "{RECIPE_ID}",
       "type": "recipe",
       "attributes": {
         "activation_config": {
           "variables": [{
             "title": "Email to fill a \"CC\" field",
             "key": "emailCc"
           }]
         },
         "marketplace_content": {
           "title": "My Recipe",
           "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
           "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
           "help_text": "No setup required",
           "tags": []
         },
         "flow_template": {
           "cron": "*/3 * * * *",
           "graph": {
             "nodes": [
               {
                 "name": "New name",
                 "description": "New description",
                 "command": "elasticio/petstore:getPetsByStatusWithGenerators@latest",
                 "id": "step_1"
               },
               {
                 "name": "New name",
                 "description": "New description",
                 "command": "elasticio/email:send@latest",
                 "fields": {
                   "dontThrowErrorFlg": true
                 },
                 "id": "step_2"
               }
             ],
             "edges": [
               {
                 "config": {
                   "mapper_type": "jsonata",
                   "mapper": {
                     "to": "pets[0].name",
                     "cc": "$getFlowVariables().emailCc",
                     "subject": "pets[0].id",
                     "textBody": "pets[0].status"
                   },
                   "condition": null
                 },
                 "source": "step_1",
                 "target": "step_2"
               }
             ]
           }
         }
       }
     }
   }'

Example response

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

{
  "data": {
    "id": "{RECIPE_ID}",
    "type": "recipe",
    "links": {
      "self": "/v2/recipes/{RECIPE_ID}"
    },
    "attributes": {
      "visibility": "workspace",
      "activation_config": {
        "variables": [{
          "title": "Email to fill a \"CC\" field",
          "key": "emailCc"
        }],
        "credentials": [{
          "description": "Credentials to access your Petstore",
          "stepId": "step_1"
        }]
      },
      "marketplace_content": {
        "title": "My first recipe 2nd iteration NEW",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "help_text": "No setup required",
        "tags": []
      },
      "flow_template": {
        "cron": "*/3 * * * *",
        "graph": {
          "edges": [
            {
              "config": {
                "condition": null,
                "mapper": {
                  "textBody": "pets[0].status",
                  "subject": "pets[0].id",
                  "to": "pets[0].name",
                  "cc": "$getFlowVariables().emailCc"
                },
                "mapper_type": "jsonata"
              },
              "source": "step_1",
              "target": "step_2"
            }
          ],
          "nodes": [
            {
              "name": "New name",
              "description": "New description",
              "command": "elasticio/petstore:getPetsByStatusWithGenerators@latest",
              "id": "step_1"
            },
            {
              "name": "New name",
              "description": "New description",
              "command": "elasticio/email:send@latest",
              "fields": {
                "dontThrowErrorFlg": true
              },
              "id": "step_2"
            }
          ]
        }
      },
      "created_at": "2019-09-30T11:22:19.822Z",
      "updated_at": "2019-09-30T11:22:19.822Z"
    },
    "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}"
        }
      },
      "contract": {
        "data": {
          "id": "{CONTRACT_ID}",
          "type": "contract"
        },
        "links": {
          "self": "/v2/contracts/{CONTRACT_ID}"
        }
      }
    }
  },
  "meta": {}
}

This resource allows you to update the given recipe.

HTTP Request

PATCH https://api.elastic.io/v2/recipes/{RECIPE_ID}

URL Parameters

Parameter	Required	Description
RECIPE_ID	yes	Recipe ID

Body Parameters

Parameter	Required	Description
type	yes	A value must be `recipe`
attributes.activation_config.credentials	no	List of credentials used by steps in a flow
attributes.activation_config.variables	no	List of variables used by steps in a flow
attributes.marketplace_content.name	no	Recipe name
attributes.marketplace_content.description	no	Recipe description
attributes.marketplace_content.short_description	no	Recipe short description
attributes.marketplace_content.help_text	no	Recipe help text
attributes.flow_template.cron	no	Cron expression
attributes.flow_template.graph	yes	Recipe graph representing component connections
relationships.workspace.data.id	yes	MUST be the same as the {RECIPE_ID}
relationships.workspace.data.type	yes	A value must be `workspace`

Authorization

This request is authorized for a user with the workspaces.recipe.edit permission.

Returns

Returns the updated recipe

Update a recipe visibility

Example request

curl https://api.elastic.io/v2/recipes/{RECIPE_ID}/visibility \
  -X PATCH \
  -u {EMAIL}:{APIKEY} \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' -d '
   {
     "data": {
       "visibility": "contract"
     }
   }'

Example response

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

{
  "data": {
    "id": "{RECIPE_ID}",
    "type": "recipe",
    "links": {
      "self": "/v2/recipes/{RECIPE_ID}"
    },
    "attributes": {
      "visibility": "contract",
      "activation_config": {
        "variables": [{
          "title": "Email to fill a \"CC\" field",
          "key": "emailCc"
        }],
        "credentials": [{
          "description": "Credentials to access your Petstore",
          "stepId": "step_1"
        }]
      },
      "marketplace_content": {
        "title": "My first recipe 2nd iteration NEW",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "short_description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "help_text": "No setup required",
        "tags": []
      },
      "flow_template": {
        "cron": "*/3 * * * *",
        "graph": {
          "edges": [
            {
              "config": {
                "condition": null,
                "mapper": {
                  "textBody": "pets[0].status",
                  "subject": "pets[0].id",
                  "to": "pets[0].name",
                  "cc": "$getFlowVariables().emailCc"
                },
                "mapper_type": "jsonata"
              },
              "source": "step_1",
              "target": "step_2"
            }
          ],
          "nodes": [
            {
              "name": "New name",
              "description": "New description",
              "command": "elasticio/petstore:getPetsByStatusWithGenerators@latest",
              "id": "step_1"
            },
            {
              "name": "New name",
              "description": "New description",
              "command": "elasticio/email:send@latest",
              "fields": {
                "dontThrowErrorFlg": true
              },
              "id": "step_2"
            }
          ]
        }
      },
      "created_at": "2019-09-30T11:22:19.822Z",
      "updated_at": "2019-09-30T11:22:19.822Z"
    },
    "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}"
        }
      },
      "contract": {
        "data": {
          "id": "{CONTRACT_ID}",
          "type": "contract"
        },
        "links": {
          "self": "/v2/contracts/{CONTRACT_ID}"
        }
      }
    }
  },
  "meta": {}
}

This resource allows you to update attribute visibility of the given recipe.

HTTP Request

PATCH https://api.elastic.io/v2/recipes/{RECIPE_ID}/visibility

URL Parameters

Parameter	Required	Description
RECIPE_ID	yes	Recipe ID

Body Parameters

Parameter	Required	Description
visibility	yes	Recipe sharing mode. Value must be one of `workspace`, `contract`, `tenant` or `global`

Authorization

This request is authorized depend on specified visibility level for a user that has next permission:

to tenant if user has permission tenant.recipe.edit_visibility_tenant
to global if user has permission global.recipe.edit_visibility_global
to contract if user has permission workspaces.recipe.edit
to workspace if user has permission workspaces.recipe.edit

Returns

Returns the updated recipe

Activate a recipe

Example request

curl https://api.elastic.io/v2/recipes/{RECIPE_ID}/activate \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
   {
     "data": {
       "type": "recipe-activation-config",
       "attributes": {
         "name": "Flow, created from Recipe",
         "description": "Recipe description",
         "credentials": {
           "step_1": "{CREDENTIAL_ID}"
         },
         "variables": {
           "TO_EMAIL": "goose@example.com",
           "NAME_IN_SUBJECT": "Neochen Jubata"
         },
         "fields": {
           "step_1": {
             "code": "console.log(message)"
           },
           "step_3":  {
             "email": "email@example.com"
           }
         }
       },
       "relationships": {
         "workspace": {
           "data": {
             "type": "workspace",
             "id": "{WORKSPACE_ID}"
           }
         }
       }
     }
   }'

Example response

HTTP/1.1 201 Created
{
  "data": {
    "relationships": {
      "flow": {
        "data": {
          "type": "flow",
          "id": "{FLOW_ID}"
        },
        "links": {
          "self": "/v2/flows/{FLOW_ID}"
        }
      }
    }
  },
  "meta": {}
}

Create a flow from a recipe. If the recipe contains a component, which requires a credential, it should be provided among the request payload.

HTTP Request

POST https://api.elastic.io/v2/recipes/{RECIPE_ID}/activate

URL Parameters

Parameter	Required	Description
RECIPE_ID	Yes	Recipe identifier

Body Parameters

Parameter	Required	Description
type	yes	A value must be `recipe-activation-config`
attributes.name	no	Flow name
attributes.credentials	no	Specify component credentials if needed
attributes.variables	yes	Specify values for variables which were defined in Recipe for mapping
attributes.fields	no	Specify fields for Recipe steps
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 an ID of created Flow

Delete a recipe

Example Request:

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

This resource allows you to delete a recipe.

HTTP Request

DELETE https://api.elastic.io/v2/recipe/{RECIPE_ID}

URL Parameters

Parameter	Required	Description
RECIPE_ID	yes	Recipe ID

Example Response:

HTTP/1.1 200 Ok
{
  "data": null,
  "meta": {
    "unlinked_flows": [

    ]
  }
}

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

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:

selectModel allows retrieving available options for certain parameter of configuration, when component/module is used in some node in some flow
getMetaModel allows retrieving metadata for certain configuration of some node of some flow
verifyCredentials allows 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 the Location HTTP header is the URL to poll for execution results.
The execution result is polled periodically by sending requests to the polling resourceexec/poll/{EXECUTION_ID}. The API responds with 200 OK if the result is not available yet. Please see how to poll execution results.
Once the result is available the polling resource responds with 303 See Other. The resource in the Location HTTP header is the URL to get the results of the execution. Please see how to poll execution results.
The results are retrieved from exec/result/{EXECUTION_ID}. Please see how to retrieve execution results.

Scheduled Executions

Verify credentials

Example Request:

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

Snapshots

This group of API endpoints allows you to work with snapshots feature of the Platform. The feature enables taking snapshots for all steps in a Flow. Also, it allows you to get/create/edit/remove snapshots individually for steps.

Data model: every step in Flow can have associated persistent data. Step identifier is used as identifier of snapshot. Data may be anything serializable in JSON, except undefined.

Notice: snapshot is flow’s runtime data. So it’s forbidden to edit snapshots while flow is running.

Retrieve snapshots for all steps in flow

Example Request:

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

Example Response:

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

{
  "data":[
    {
      "id":"{STEP_ID}",
      "type":"snapshot",
      "links":{
        "self":"/v2/flows/{FLOW_ID}/snapshots/{STEP_ID}"
      },
      "attributes":{
        "snapshot":"{BODY OF SNAPSHOT}"
      }
    },
    {
      "id":"{STEP_ID}",
      "type":"snapshot",
      "links":{
        "self":"/v2/flows/{FLOW_ID}/snapshots/{STEP_ID}"
      },
      "attributes":{
        "snapshot":"{BODY OF SNAPSHOT}"
      }
    },
    {
      "id":"{STEP_ID}",
      "type":"snapshot",
      "links":{
        "self":"/v2/flows/{FLOW_ID}/snapshots/{STEP_ID}"
      },
      "attributes":{
        "snapshot":"{BODY OF SNAPSHOT}"
      }
    }
  ],
  "meta":{}
}

This resource allows you to retrieve snapshots for all steps in flow

HTTP Request

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

Authorization

The client has to be a member of the Workspace’s scope, where the specified Flow is located

URL Parameters

Parameter	Description
FLOW_ID	The ID of the Flow

Retrieve snapshot for one step in flow

Example Request:

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

Example Response:

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

{
  "data":{
    "id":"{STEP_ID}",
    "type":"snapshot",
    "links":{
      "self":"/v2/flows/{FLOW_ID}/snapshots/{STEP_ID}"
    },
    "attributes":{
      "snapshot":"{BODY OF SNAPSHOT}"
    }
  },
  "meta":{}
}

This resource allows you to retrieve snapshot for one step in flow

HTTP Request

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

Authorization

The client has to be a member of the Workspace’s scope, where the specified Flow is located

URL Parameters

Parameter	Description
FLOW_ID	The ID of the Flow
STEP_ID	ID of the Step from the specified Flow

Edit snapshot for one step in flow

Example Request:

curl https://api.elastic.io/v2/flows/{FLOW_ID}/snapshots/{STEP_ID} \
   -X PATCH \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
   {
     "data":{
       "type":"snapshot",
       "id":"{STEP_ID}",
       "attributes":{
         "snapshot":"{BODY OF SNAPSHOT}"
       }
     }
   }'

Example Response:

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

{
  "data":{
    "id":"{STEP_ID}",
    "type":"snapshot",
    "links":{
      "self":"/v2/flows/{FLOW_ID}/snapshots/{STEP_ID}"
    },
    "attributes":{
      "snapshot":"{BODY_OF_SNAPSHOT}"
    }
  },
  "meta":{}
}

This resource allows you to edit snapshot for step in flow.

HTTP Request

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

Authorization

This request is authorized to a user with the workspaces.flow.edit permission.

URL Parameters

Parameter	Description
FLOW_ID	The ID of the Flow
STEP_ID	ID of the Step from the specified Flow

Notices

It’s forbidden to edit snapshot for step, that does not exist in flow.
It’s forbidden to edit snapshot for step, if no snapshot exists.

Create snapshot for one step in flow

Example Request:

curl https://api.elastic.io/v2/flows/{FLOW_ID}/snapshots/ \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
{
  "data":{
    "type":"snapshot",
    "id":"{STEP_ID}",
    "attributes":{
      "snapshot":"{BODY OF SNAPSHOT}"
    }
  }
}'

Example Response:

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

{
  "data":{
    "id":"{STEP_ID}",
    "type":"snapshot",
    "links":{
      "self":"/v2/flows/{FLOW_ID}/snapshots/{STEP_ID}"
    },
    "attributes":{
      "snapshot":"{BODY_OF_SNAPSHOT}"
    }
  },
  "meta":{}
}

This resource allows you to create snapshot for step in flow.

HTTP Request

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

Authorization

This request is authorized to a user with the workspaces.flow.edit permission.

URL Parameters

Parameter	Description
FLOW_ID	The ID of the Flow

Payload Parameters

Parameter	Required	Description
id	yes	ID of the Step from the specified Flow
attributes.snapshot	yes	The body of the snapshot. The value may be anything except `undefined`

Notices

It’s forbidden to create snapshot for step, that does not exist in flow.
It’s forbidden to create snapshot for step, if snapshot already exists.

Remove snapshot for one step in flow

Example Request:

curl https://api.elastic.io/v2/flows/{FLOW_ID}/snapshots/{STEP_ID} \
    -X DELETE
    -u {EMAIL}:{APIKEY} \
    -H 'Accept: application/json'

Example Response:

HTTP/1.1 204 No Content
Content-Type: application/json

This resource allows you to remove a step snapshot in a Flow.

HTTP Request

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

Authorization

This request is authorized to a user with the workspaces.flow.edit permission.

URL Parameters

Parameter	Description
FLOW_ID	The ID of the Flow
STEP_ID	ID of the Step from the specified Flow

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

Stats

Retrieve the Amount of Messages in Input Queues of All Steps in the Flow

Example Request:

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

Example Response:

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

{
 "data": {
    "id": "{FLOW_ID}",
    "type": "flow-queue-stats",
    "attributes": {
      "stats": [
        {
          "step_id": "step_1",
          "total": 10,
          "ready": 8,
          "unacked": 2,
          "rebounds": 10
        },
        {
          "step_id": "step_2",
          "total": 20,
          "ready": 20,
          "unacked": 0,
          "rebounds": 0
        }
      ]
    }
  }
}

This endpoint allows you to retrieve the amount of messages in input queues of all steps in the flow.

HTTP Request

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

URL Parameters

Parameter	Required	Description
FLOW_ID	Yes	Flow ID

Authorization

This request is authorized for any member of the given Workspace.

Returns

Amount of messages in input queues of all steps in the Flow.

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, basically) that allows customizing all the necessary parameters by sending a particular request to the API.

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.example.com/logo-mini.png",
      "loading_logo_url":"//cdn.example.com/logo-mini.png",
      "email_logo_url":"//cdn.example.com/logo-mini.png",
      "favicon_url":"//cdn.example.com/logo-mini.png",
      "terms_of_usage_url":"https://www.example.com/tou/",
      "privacy_policy_url":"https://www.example.com/privacy-policy/",
      "imprint_url":"https://www.example.com/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,
      "docs_base_url":"https://docs.example.com/",
      "component_docs_base_url":"https://docs.example.com/components/",
      "default_workspace_type":"limited",
      "custom_stylesheets":[
        {
          "href":"http://path-to-1.css"
        },
        {
          "href":"http://path-to-2.css"
        }
      ],
      "custom_scripts":[
        {
          "src":"http://path-to-1.js"
        },
        {
          "src":"http://path-to-2.js"
        }
      ],
      "settings":{
        "member_api_key":false
      },
      "email_templates":{
        "agent-request": true,
        "contract-deleted": true,
        "contract-invite-empty-contract": true,
        "contract-invite-new-user": true,
        "contract-suspended": true,
        "contract-unsuspended": true,
        "password-recovery": true,
        "repo-new-version": false,
        "repo-new-version-in-workspace-flows": false,
        "task-error-notification": true,
        "task-operational-error": true,
        "team-from-contract-invite": true,
        "team-removed-member": true,
        "user-removed-from-contract": true,
        "wiper-exhaustion-quota-notification": true,
        "wiper-flow-suspended-due-to-queue-overflow": true,
        "wiper-suspended-queue-purged": true,
        "workspace-invite-empty-workspace": true,
        "workspace-invite-new-user": true,
        "workspace-removed": true,
        "workspace-removed-member": true
      },
      "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",
              "target":"modal"
            },
            {
              "url":"https://components-catalog.example.com?workspaceId={workspaceId}&contractId={contractId}",
              "title":"Components catalog",
              "icon":"components-catalog-icon",
              "custom_class":"custom_class",
              "target":"modal"
            }
          ]
        },
        {
          "title":"Quick Help",
          "icon":"help",
          "custom_class":"custom_class",
          "links":[
            {
              "url":"https://docs.example.com",
              "title":"Documentation",
              "icon":"description",
              "target":"_blank"
            },
            {
              "title":"Help Center",
              "icon":"forum",
              "custom_class":"intercom-launcher"
            }
          ]
        }
      ],
      "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.example.com/logo-mini.png",
      "loading_logo_url":"//cdn.example.com/logo-mini.png",
      "email_logo_url":"//cdn.example.com/logo-mini.png",
      "favicon_url":"//cdn.example.com/logo-mini.png",
      "terms_of_usage_url":"https://www.example.com/tou/",
      "privacy_policy_url":"https://www.example.com/privacy-policy/",
      "imprint_url":"https://www.example.com/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,
      "docs_base_url":"https://docs.example.com/",
      "component_docs_base_url":"https://docs.example.com/components/",
      "default_workspace_type":"limited",
      "ssl_certificates":{},
      "custom_stylesheets":[
        {
          "href":"http://path-to-1.css"
        },
        {
          "href":"http://path-to-2.css"
        }
      ],
      "custom_scripts":[
        {
          "src":"http://path-to-1.js"
        },
        {
          "src":"http://path-to-2.js"
        }
      ],
      "email_templates":{
        "agent-request": true,
        "contract-deleted": true,
        "contract-invite-empty-contract": true,
        "contract-invite-new-user": true,
        "contract-suspended": true,
        "contract-unsuspended": true,
        "password-recovery": true,
        "repo-new-version": false,
        "repo-new-version-in-workspace-flows": false,
        "task-error-notification": true,
        "task-operational-error": true,
        "team-from-contract-invite": true,
        "team-removed-member": true,
        "user-removed-from-contract": true,
        "wiper-exhaustion-quota-notification": true,
        "wiper-flow-suspended-due-to-queue-overflow": true,
        "wiper-suspended-queue-purged": true,
        "workspace-invite-empty-workspace": true,
        "workspace-invite-new-user": true,
        "workspace-removed": true,
        "workspace-removed-member": true
      },
      "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",
              "target":"modal"
            },
            {
              "url":"https://components-catalog.example.com?workspaceId={workspaceId}&contractId={contractId}",
              "title":"Components catalog",
              "icon":"components-catalog-icon",
              "custom_class":"custom_class",
              "target":"modal"
            }
          ]
        },
        {
          "title":"Quick Help",
          "icon":"help",
          "custom_class":"custom_class",
          "links":[
            {
              "url":"https://docs.example.com",
              "title":"Documentation",
              "icon":"description",
              "target":"_blank"
            },
            {
              "title":"Help Center",
              "icon":"forum",
              "custom_class":"intercom-launcher"
            }
          ]
        }
      ],
      "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.mandrill_email_from	yes	An email of the letters sender
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_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.docs_base_url	no	This link will applied to the Quick Help =>> Documentation menu and to the repository page docs link
attributes.component_docs_base_url	no	Base URL for relative paths to component docs. E.g. if this url is `https://docs.example.com/` and `component.json` contains the following field `"help": {"link": "salesforce"}`, we will use `https://docs.example.com/salesforce` as a link to documentation of this component on the frontend. If this property is not set, relative urls won’t be displayed. If this property is set, make sure `component_docs_base_url` and ‘getting-started/credential.html’ page exists
attributes.css_enabled	no	A value should be true or false
attributes.email_templates	no	A hashMap of represent emails will be sent. By default “repo-new-version” and “repo-new-version-in-workspace-flows” are set to false
attributes.settings.member_api_key	no	A value should be true or false
attributes.custom_nav_menu_items	no	The custome menu
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.custom_nav_menu_items[].links[].target	no	A value can be `modal` or `_blank`. In case of “target”=“modal” link will be opened in the modal window. In case of “target”:“blank”, link will be opened in the new tab. The value by default is `blank`
attributes.custom_stylesheets[]	no	Customer css stylesheets
attributes.custom_scripts[]	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 `full`or `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",
      "docs_base_url":"https://docs.example.com/",
      "component_docs_base_url":"https://docs.example.com/components/",
      "email_templates":{
        "agent-request": true,
        "contract-deleted": true,
        "contract-invite-empty-contract": true,
        "contract-invite-new-user": true,
        "contract-suspended": true,
        "contract-unsuspended": true,
        "password-recovery": true,
        "repo-new-version": false,
        "repo-new-version-in-workspace-flows": false,
        "task-error-notification": true,
        "task-operational-error": true,
        "team-from-contract-invite": true,
        "team-removed-member": true,
        "user-removed-from-contract": true,
        "wiper-exhaustion-quota-notification": true,
        "wiper-flow-suspended-due-to-queue-overflow": true,
        "wiper-suspended-queue-purged": true,
        "workspace-invite-empty-workspace": true,
        "workspace-invite-new-user": true,
        "workspace-removed": true,
        "workspace-removed-member": true
      },
      "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",
              "target":"modal"
            },
            {
              "url":"https://components-catalog.example.com?workspaceId={workspaceId}&contractId={contractId}",
              "title":"Components catalog",
              "icon":"components-catalog-icon",
              "custom_class":"custom_class",
              "target":"modal"
            }
          ]
        },
        {
          "title":"Quick Help",
          "icon":"help",
          "custom_class":"custom_class",
          "links":[
            {
              "url":"https://docs.example.com",
              "title":"Documentation",
              "icon":"description",
              "target":"_blank"
            },
            {
              "title":"Help Center",
              "icon":"forum",
              "custom_class":"intercom-launcher"
            }
          ]
        }
      ],
      "custom_stylesheets":[
        {
          "href":"http://path-to-1.css"
        },
        {
          "href":"http://path-to-2.css"
        }
      ],
      "custom_scripts":[
        {
          "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.example.com/logo-mini.png",
      "loading_logo_url":"//cdn.example.com/logo-mini.png",
      "email_logo_url":"//cdn.example.com/logo-mini.png",
      "favicon_url":"//cdn.example.com/logo-mini.png",
      "terms_of_usage_url":"https://www.example.com/tou/",
      "privacy_policy_url":"https://www.example.com/privacy-policy/",
      "imprint_url":"https://www.example.com/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,
      "docs_base_url":"https://docs.example.com/",
      "component_docs_base_url":"https://docs.example.com/components/",
      "default_workspace_type":"full",
      "custom_stylesheets":[
        {
          "href":"http://path-to-1.css"
        },
        {
          "href":"http://path-to-2.css"
        }
      ],
      "custom_scripts":[
        {
          "src":"http://path-to-1.js"
        },
        {
          "src":"http://path-to-2.js"
        }
      ],
      "ssl_certificates":{
        "app":"{{cert_id}}",
        "api":"{{cert_id}}",
        "webhooks":"{{cert_id}}"
      },
      "email_templates":{
        "agent-request": true,
        "contract-deleted": true,
        "contract-invite-empty-contract": true,
        "contract-invite-new-user": true,
        "contract-suspended": true,
        "contract-unsuspended": true,
        "password-recovery": true,
        "repo-new-version": false,
        "repo-new-version-in-workspace-flows": false,
        "task-error-notification": true,
        "task-operational-error": true,
        "team-from-contract-invite": true,
        "team-removed-member": true,
        "user-removed-from-contract": true,
        "wiper-exhaustion-quota-notification": true,
        "wiper-flow-suspended-due-to-queue-overflow": true,
        "wiper-suspended-queue-purged": true,
        "workspace-invite-empty-workspace": true,
        "workspace-invite-new-user": true,
        "workspace-removed": true,
        "workspace-removed-member": true
      },
      "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",
              "target":"modal"
            },
            {
              "url":"https://components-catalog.example.com?workspaceId={workspaceId}&contractId={contractId}",
              "title":"Components catalog",
              "icon":"components-catalog-icon",
              "custom_class":"custom_class",
              "target":"modal"
            }
          ]
        },
        {
          "title":"Quick Help",
          "icon":"help",
          "custom_class":"custom_class",
          "links":[
            {
              "url":"https://docs.example.com",
              "title":"Documentation",
              "icon":"description",
              "target":"_blank"
            },
            {
              "title":"Help Center",
              "icon":"forum",
              "custom_class":"intercom-launcher"
            }
          ]
        }
      ],
      "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	Allowed values: `true`, `false`
attributes.hide_teams	no	Allowed values: `true`, `false`
attributes.hide_ssh_keys	no	Allowed values: `true`, `false`
attributes.hide_api_key	no	Allowed values: `true`, `false`
attributes.hide_docs	no	Allowed values: `true`, `false`
attributes.powered_by_elasticio	no	Allowed values: `true`, `false`
attributes.css_enabled	no	Allowed values: `true`, `false`
attributes.email_templates	no	A hashMap of represent emails will be sent. By default “repo-new-version” and “repo-new-version-in-workspace-flows” are set to false
attributes.settings.member_api_key	no	Allowed values: `true`, `false`
attributes.email_templates	no	A hashMap of represent emails will be sent. By default “repo-new-version” and “repo-new-version-in-workspace-flows” are set to 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.docs_base_url	no	This link will applied to the Quick Help =>> Documentation menu and to the repository page docs link
attributes.component_docs_base_url	no	Base URL for relative paths to component docs. E.g. if this url is `https://docs.example.com/components/` and `component.json` contains the following field `"help": {"link": "salesforce"}`, on frontend we will use `https://docs.example.com/components/salesforce` as a link to documentation of this component. If this property is not set, relative urls won’t be displayed. If this property is set, make sure component_docs_base_url + 'getting-started/credential.html’ page exists
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.custom_nav_menu_items[].links[].target	no	A value can be `modal` or `_blank`. In case of “target”=“modal” link will be opened in the modal window. In case of “target”:“blank”, link will be opened in the new tab. The value by default is `blank`
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.custom_stylesheets[]	no	Customer css stylesheets.
attributes.custom_scripts[]	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 the default installation’s certificate is a wildcard one (e.g. *.example.com) and the Tenant’s domains match to this certificate (e.g. my-tenant-api.example.com), then there is no need to provide separate certificates for these domains. To remove existing certificates, set them to 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.example.com/logo-mini.png",
        "loading_logo_url":"//cdn.example.com/logo-mini.png",
        "email_logo_url":"//cdn.example.com/logo-mini.png",
        "favicon_url":"//cdn.example.com/logo-mini.png",
        "terms_of_usage_url":"https://www.example.com/tou/",
        "privacy_policy_url":"https://www.example.com/privacy-policy/",
        "imprint_url":"https://www.example.com/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,
        "docs_base_url":"https://docs.example.com/",
        "component_docs_base_url":"https://docs.example.com/components/",
        "ssl_certificates":{},
      "email_templates":{
        "agent-request": true,
        "contract-deleted": true,
        "contract-invite-empty-contract": true,
        "contract-invite-new-user": true,
        "contract-suspended": true,
        "contract-unsuspended": true,
        "password-recovery": true,
        "repo-new-version": false,
        "repo-new-version-in-workspace-flows": false,
        "task-error-notification": true,
        "task-operational-error": true,
        "team-from-contract-invite": true,
        "team-removed-member": true,
        "user-removed-from-contract": true,
        "wiper-exhaustion-quota-notification": true,
        "wiper-flow-suspended-due-to-queue-overflow": true,
        "wiper-suspended-queue-purged": true,
        "workspace-invite-empty-workspace": true,
        "workspace-invite-new-user": true,
        "workspace-removed": true,
        "workspace-removed-member": true
      },
        "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",
                "target":"modal"
              },
              {
                "url":"https://components-catalog.example.com?workspaceId={workspaceId}&contractId={contractId}",
                "title":"Components catalog",
                "icon":"components-catalog-icon",
                "custom_class":"custom_class",
                "target":"modal"
              }
            ]
          },
          {
            "title":"Quick Help",
            "icon":"help",
            "custom_class":"custom_class",
            "links":[
              {
                "url":"https://docs.example.com",
                "title":"Documentation",
                "icon":"description",
                "target":"_blank"
              },
              {
                "title":"Help Center",
                "icon":"forum",
                "custom_class":"intercom-launcher"
              }
            ]
          }
        ],
        "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.example.com/logo-mini.png",
      "loading_logo_url":"//cdn.example.com/logo-mini.png",
      "email_logo_url":"//cdn.example.com/logo-mini.png",
      "favicon_url":"//cdn.example.com/logo-mini.png",
      "terms_of_usage_url":"https://www.example.com/tou/",
      "privacy_policy_url":"https://www.example.com/privacy-policy/",
      "imprint_url":"https://www.example.com/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,
      "docs_base_url":"https://docs.example.com/",
      "component_docs_base_url":"https://docs.example.com/components/",
      "ssl_certificates":{},
      "email_templates":{
        "agent-request": true,
        "contract-deleted": true,
        "contract-invite-empty-contract": true,
        "contract-invite-new-user": true,
        "contract-suspended": true,
        "contract-unsuspended": true,
        "password-recovery": true,
        "repo-new-version": false,
        "repo-new-version-in-workspace-flows": false,
        "task-error-notification": true,
        "task-operational-error": true,
        "team-from-contract-invite": true,
        "team-removed-member": true,
        "user-removed-from-contract": true,
        "wiper-exhaustion-quota-notification": true,
        "wiper-flow-suspended-due-to-queue-overflow": true,
        "wiper-suspended-queue-purged": true,
        "workspace-invite-empty-workspace": true,
        "workspace-invite-new-user": true,
        "workspace-removed": true,
        "workspace-removed-member": true
      },
     "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",
              "target":"modal"
            },
            {
              "url":"https://components-catalog.example.com?workspaceId={workspaceId}&contractId={contractId}",
              "title":"Components catalog",
              "icon":"components-catalog-icon",
              "custom_class":"custom_class",
              "target":"modal"
            }
          ]
        },
        {
          "title":"Quick Help",
          "icon":"help",
          "custom_class":"custom_class",
          "links":[
            {
              "url":"https://docs.example.com",
              "title":"Documentation",
              "icon":"description",
              "target":"_blank"
            },
            {
              "title":"Help Center",
              "icon":"forum",
              "custom_class":"intercom-launcher"
            }
          ]
        }
      ],
  "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.recipe.edit",
        "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.
`global.quota_limits.edit`	Set or update quota limits.
`global.contract.contract.list_all`	List all contracts
`global.workspace.get_all`	List all Workspaces
`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).

Create an OpenID Provider

Example Request:

 curl https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
   {
     "data":{
       "type":"openid-provider",
       "attributes":{
         "issuer": "{ISSUER}",
         "client_id":"{CLIENT_ID}",
         "response_type": "code",
         "client_secret":"{CLIENT_SECRET}"
       }
     }
   }'

Example Response:

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data":{
    "id": "5c80e6b9bb0d200011333d92",
    "type": "openid-provider",
    "attributes": {
        "client_id": "c7e56633-5e88-4c97-8da9-f823432423",
        "client_secret": "c7e56633-5e88-4c97-8da9-f823432423",
        "issuer": "https://issuer.com",
        "response_type": "code",
        "config": {
            "auto_create_users": true
        }
    },
    "relationships": {
      "tenant": {
        "data": {
            "id": "5c80e6b9bb0d200011333d93",
            "type": "tenant"
        },
        "links": {
            "self": "/v2/tenants/5c80e6b9bb0d200011333d93"
        }
      }
    }
  },
  "meta":{}
}

This resource allows you to create a new OpenID Provider.

HTTP Request

POST https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers

Authorization

This request is authorized for the users with the tenants.tenant.edit permission.

Payload Parameters

Parameter	Required	Description
type	yes	A value should be “openid-provider”
attributes.issuer	yes	OpenID Provider issuer
attributes.client_id	yes	OpenID Provider client ID
attributes.client_secret	yes	OpenID Provider client secret
attributes.response_type	no	A value should be “code”
attributes.config.auto_create_users	no	A value should be true or false

URL Parameters

Parameter	Description
TENANT_ID	The ID of the Tenant

Returns

Returns OpenID Provider object if the call succeeded

Retrieve an OpenID Providers

Example Request:

 curl https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers \
   -u {EMAIL}:{APIKEY}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data":[
    {
      "id": "5c80e6b9bb0d200011333d92",
      "type": "openid-provider",
      "attributes": {
          "client_id": "c7e56633-5e88-4c97-8da9-f823432423",
          "client_secret": "c7e56633-5e88-4c97-8da9-f823432423",
          "issuer": "https://issuer.com",
          "response_type": "code",
          "config": {
              "auto_create_users": true
          }
      },
      "relationships": {
        "tenant": {
          "data": {
              "id": "5c80e6b9bb0d200011333d93",
              "type": "tenant"
          },
          "links": {
              "self": "/v2/tenants/5c80e6b9bb0d200011333d93"
          }
        }
      }
    }
  ],
  "meta":{}
}

This resource allows you to retrieve OpenID Providers for the Tenant with the given ID.

HTTP Request

GET https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	The ID of the Tenant

Authorization

This request is authorized for the users with the tenants.tenant.get permission.

Returns

Returns OpenID Provider objects if the call succeeded

Retrieve an OpenID Provider by ID

Example Request:

 curl https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers/{OPEN_ID_PROVIDER_ID} \
   -u {EMAIL}:{APIKEY}

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data":{
    "id": "5c80e6b9bb0d200011333d92",
    "type": "openid-provider",
    "attributes": {
        "client_id": "c7e56633-5e88-4c97-8da9-f823432423",
        "client_secret": "c7e56633-5e88-4c97-8da9-f823432423",
        "issuer": "https://issuer.com",
        "response_type": "code",
        "config": {
            "auto_create_users": true
        }
    },
    "relationships": {
      "tenant": {
        "data": {
            "id": "5c80e6b9bb0d200011333d93",
            "type": "tenant"
        },
        "links": {
            "self": "/v2/tenants/5c80e6b9bb0d200011333d93"
        }
      }
    }
  },
  "meta":{}
}

This resource allows you to retrieve a OpenID Provider with the given ID for the Tenant with the given ID.

HTTP Request

GET https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers/{OPEN_ID_PROVIDER_ID}

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	The ID of the Tenant
OPEN_ID_PROVIDER_ID	yes	The ID of the OpenID Provider

Authorization

This request is authorized for the users with the tenants.tenant.get permission.

Returns

Returns OpenID Provider object if the call succeeded

Update an OpenID Provider

Example Request:

 curl https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers/{OPEN_ID_PROVIDER_ID} \
   -X PATCH \
   -u {EMAIL}:{APIKEY} \
   -H 'Content-Type: application/json' -d '
   {
     "data":{
       "type":"openid-provider,
       "attributes":{
         "issuer": "{ISSUER}"
         "client_id":"{CLIENT_ID}",
         "client_secret":"{CLIENT_SECRET}",
         "config": {
           "auto_create_users": true
         }
       }
     }
   }'

Example Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data":{
    "id": "5c80e6b9bb0d200011333d92",
    "type": "openid-provider",
    "attributes": {
        "client_id": "c7e56633-5e88-4c97-8da9-f823432423",
        "client_secret": "c7e56633-5e88-4c97-8da9-f823432423",
        "issuer": "https://issuer.com",
        "response_type": "code",
        "config": {
            "auto_create_users": true
        }
    },
    "relationships": {
      "tenant": {
        "data": {
            "id": "5c80e6b9bb0d200011333d93",
            "type": "tenant"
        },
        "links": {
            "self": "/v2/tenants/5c80e6b9bb0d200011333d93"
        }
      }
    }
  },
  "meta":{}
}

This resource allows you to update an OpenID Provider with the given ID for the Tenant with the given ID.

HTTP Request

PATCH https://api.elastic.io/v2/tenants/{TENANT_ID}/openid/providers/{OPEN_ID_PROVIDER_ID}

Authorization

This request is authorized for the users with the tenants.tenant.edit permission.

URL Parameters

Parameter	Required	Description
TENANT_ID	yes	The ID of the Tenant
OPEN_ID_PROVIDER_ID	yes	The ID of the OpenID Provider

Payload Parameters

Parameter	Required	Description
type	yes	A value should be “openid-provider”
attributes.issuer	no	OpenID Provider issuer
attributes.client_id	no	OpenID Provider client ID
attributes.client_secret	no	OpenID Provider client secret
attributes.response_type	no	A value should be “code”
attributes.config.auto_create_users	no	A value should be true or false

Returns

Returns Oauth-client object if the call succeeded

List of emails sent by the Platform

The Platform sends various emails when triggered. Here is the list of templates that you can customize:

agent-request Agent has been requested
contract-deleted Contract has been deleted
contract-invite-empty-contract New user has been invited to an empty Contract
contract-invite-new-user New user has been invited to the Contract
contract-suspended Contract has been suspended
contract-unsuspended Contract has been unsuspended
password-recovery Password recovery has been requested
repo-new-version New Component version has been pushed in your Developer Team
repo-new-version-in-workspace-flows New Component version has been pushed, Component used in your Flows
task-error-notification A Component has reported an error
task-operational-error A container has failed
team-from-contract-invite Has invited to contract’s team
team-removed-member Team member has been removed
user-removed-from-contract Has removed user from contract
wiper-exhaustion-quota-notification Quota usage has come to the limit
wiper-flow-suspended-due-to-queue-overflow Flow has been suspended due to queue overflow
wiper-suspended-queue-purged Unhandled data has been purged
workspace-invite-empty-workspace User has been invited to an empty Workspace
workspace-invite-new-user Unregistered user has been invited to the Workspace
workspace-removed Workspace has been removed
workspace-removed-member Member has been removed from the Workspace

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 on successful call.

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
iss	No	Users must have OpenId identity equal to this value. Can’t be used with “email” parameter
sub	No	Users must have OpenId subject equal to this value. Can’t be used with “email” parameter
email	No	Users must have email equal to this value

Authorization

This request is authorized for users with the tenants.user.list_all permission.

Returns

Returns a list of user objects on successful call.

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 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), so they won’t be deleted right after User deletion:

Flows activity records (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 them 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 them 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 they will be deleted along with Contract and all the unique data connected with this User.

Authorization

This request is authorized for 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

Create an openid-identity

Example Request:

curl https://api.elastic.io/v2/users/{USER_ID}/openid/identities \
   -X POST \
   -u {EMAIL}:{APIKEY} \
   -H 'Accept: application/json' \
   -H 'Content-Type: application/json' -d '
    {
        "data":{
            "type":"openid-identity",
            "attributes":{
                "iss":"http://example.com",
                "sub":"user-identification"
            }
        }
    }'

Example Response:

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

{
  "data":{
    "id":"{OPENID_IDENTITY_ID}",
    "type":"user",
    "links":{
      "self":"/v2/users/{USER_ID}/openid/identities/{OPENID_IDENTITY_ID}"
    },
    "attributes":{
       "iss":"http://example.com",
       "sub":"user-identification"
    },
    "relationships":{
        "user":{
            "data":{
                "type":"user",
                "id":"{USER_ID}"
            },
            "links":{
                "self":"/v2/users/{USER_ID}"
            }
        }
    }
  },
  "meta":{}
}

This resource allows you to create an OpenID Identity for a user.

HTTP Request

POST https://api.elastic.io/v2/users/{USER_ID}/openid/identities

Body Parameters

Parameter	Required	Description
type	yes	A value must be `openid-identity`
attributes.iss	yes	User’s OpenID Identity issuer. Must be an URL.
attributes.sub	yes	User’s OpenID Identity subject.

URL Parameters

Parameter	Required	Description
USER_ID	yes	User identifier

Data associated with User

A user can have multiple OpenID Identities.

Authorization

This request is authorized for users with the tenants.oidc.create permission.

Returns

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

Delete an openid-identity

Example Request:

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

Example Response:

HTTP/1.1 204 No Content

This resource allows you to create an OpenID Identity for a user.

HTTP Request

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

URL Parameters

Parameter	Required	Description
USER_ID	yes	User identifier
OPENID_IDENTITY_ID	yes	User’s OpenID Identity ID

Authorization

This request is authorized for users with the tenants.oidc.delete permission.

Workspaces

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 certain roles that define user permissions. 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	Contract ID

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 endpoint 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	Workspace ID

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	Allowed value: “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 on successful call.

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	Allowed value: “workspace”
attributes.name	yes	Name of the Workspace
attributes.type	no	Type of the Workspace. Allowed values: `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	Allowed value: “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

Returns 409 Conflict if the user is already a member of the workspace

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	Allowed value: “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	Workspace ID
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).

Introduction

Authentication

Status Codes

Success

Errors

Agents

Retrieve All Agents

HTTP Request

Query Parameters

Returns

Create Agent

HTTP Request

Body Parameters

Returns

Auth Clients (Experimental)

Retrieve All Auth Clients

HTTP Request

Authorization

URL Parameters

Query Parameters

Returns

Create Auth Client

HTTP Request

Authorization

URL Parameters

Body Parameters

Returns

Retrieve the Auth Client by ID

HTTP Request

Authorization

URL Parameters

Returns

Update the Auth Client

HTTP Request

Authorization

URL Parameters

Body Parameters

Returns

Delete Auth Client

HTTP Request

Authorization

URL Parameters

Auth Secrets (Experimental)

Retrieve All Auth Secrets

HTTP Request

Authorization

URL Parameters

Query Parameters

Returns

Create Auth Secret

HTTP Request

Authorization

URL Parameters

Body Parameters

Returns

Refresh the Auth Secret

HTTP Request

Authorization

URL Parameters

Returns

Retrieve Auth Secret by ID

HTTP Request

Authorization

URL Parameters

Returns

Update the Auth Secret

HTTP Request

Authorization

URL Parameters

Body Parameters

Returns

Delete Auth Secret

HTTP Request

Authorization

URL Parameters

Components

Accessing and sharing components

Retrieve all components

HTTP Request

HTTP Request with parameters