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 (Deprecated)
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. Auth clients can be created on any level: tenant, contract or workspace which incapsulate each other (in order), i.e client created on tenant level is available to use for creating secrets in any workspace of the tenant.
Retrieve All Auth Clients
Example Request:
curl https://api.elastic.io/v2/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_uri": "http://example.com",
"token_expires_in": 18000,
"token_uri": "{TOKEN_URI}",
"auth_uri": "{AUTH_URI}"
}
},
"relationships": {
"components": {
"data": [
{
"id": "{COMPONENT_ID}",
"type": "component"
}
]
},
"workspace": {
"data": {
"id": "{WORKSPACE_ID}",
"type": "workspace"
},
"links": {
"self": "/v2/workspace/{WORKSPACE_ID}"
}
}
},
"links": {
"self": "/v2/auth-clients/{AUTH-CLIENT_ID}"
}
}
],
"meta": {}
}
This resource allows you to retrieve Auth-clients.
HTTP Request
GET https://api.elastic.io/v2/auth-clients
Authorization
This request is authorized with one of the global.auth_clients.get, tenants.auth_clients.get, contracts.auth_clients.get or workspaces.auth_clients.get. Each permission allows to list Auth Clients in particular scope inclusively: global.auth_clients.get allows to list global clients, tenants.auth_clients.get allows to list global and tenant’s clients, contracts.auth_clients.get allows to list global, tenant’s and all tenant’s contracts clients, workspaces.auth_clients.get allows to list all global, tenant’s, contracts’ and workspaces’ clients.
auth_clients.get permissions are also used to authorize access to Auth Client’s credentials field: one can see Auth Client’s credential only if client’s scope and permission’s scope match, i.e. credentials of tenant’s Auth Client are visible for users only with tenants.auth_clients.get permissions, though tenant Auth Client itself is visible for users with workspaces.auth_clients.get.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| filter[component] | no | Filter the Auth Clients only for specific component. Must be id of Component |
| workspace_id | no* | Show Auth Clients available in the given workpspace (including contract’s, tenant’s and global auth-clients). |
| contract_id | no* | Show Auth Clients available in the given contract (including tenant’s and global auth-clients). |
| tenant_id | no* | Show Auth Clients available in the given tenant and global scope. |
* - only one of workspace_id, contract_id, tenant_id can be specified at time. If none these of parameters is specified only global clients will be returned.
Returns
Returns list of the Auth-clients.
Create Auth Client
Example Request:
curl https://api.elastic.io/v2/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_uri":"http://example.com",
"token_expires_in":18000,
"token_uri":"{TOKEN_URI}",
"auth_uri":"{AUTH_URI}"
}
},
"relationships":{
"components":{
"data":[
{
"id":"{COMPONENT_ID}",
"type":"component"
}
]
},
"workspace":{
"data":{
"id":"{WORKSPACE_ID}",
"type":"workspace"
}
}
}
}
}'
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_uri": "http://example.com",
"token_expires_in": 18000,
"token_uri": "{TOKEN_URI}",
"auth_uri": "{AUTH_URI}"
}
},
"relationships": {
"components": {
"data": [
{
"id": "{COMPONENT_ID}",
"type": "component"
}
]
},
"workspace": {
"data": {
"id": "{WORKSPACE_ID}",
"type": "workspace"
},
"links": {
"self": "/v2/workspaces/{WORKSPACE_ID}"
}
}
},
"links": {
"self": "/v2/auth-clients/{AUTH-CLIENT_ID}"
}
},
"meta": {}
}
This resource allows you to create an Auth-client. Scope where client is created is controlled by corresponding relationship: workspace, contract or tenant. No relationship means that auth-client will be created in the global scope.
HTTP Request
POST https://api.elastic.io/v2/auth-clients
Authorization
This request is authorized for the global scope with the global.auth_clients.create permission, for the tenant’s scope members with the tenants.auth_clients.create permission, for the contract’s scope members with the contracts.auth_clients.create, for the workspace’s scope members with the workspaces.auth_clients.create.
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: oauth2and other types (noauth, basic,api_key) |
| attributes.credentials | yes | Auth Client credentials (can be an empty object if Auth Client type is not oauth2) |
| 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_uri | yes (if attributes.type is oauth2) |
Auth Client refresh token URI |
| attributes.credentials.token_expires_in | no (default: 3600) | The value that will be set as expires_in in Auth Secret linked to the Auth Client after Auth Secret refresh if Auth Secret does not contain it. |
| attributes.credentials.token_uri | yes (if attributes.type is oauth2) |
Auth Client token URI |
| attributes.credentials.auth_uri | yes (if attributes.type is oauth2) |
Auth Client auth URI |
| relationships.components.data[].component.type | yes | Allowed value: component |
| relationships.components.data[].component.id | yes | Component ID |
| relationships.tenant.data.type | no | Allowed value: tenant |
| relationships.tenant.data.id | no | Tenant ID |
| relationships.contract.data.type | no | Allowed value: contract |
| relationships.contract.data.id | no | Contract ID |
| relationships.workspace.data.type | no | Allowed value: workspace |
| relationships.workspace.data.id | no | Workspace ID |
Returns
Returns the created Auth Client object.
Retrieve the Auth Client by ID
Example Request:
curl https://api.elastic.io/v2/auth-clients/{AUTH-CLIENT_ID}?workspace_id={WORKSPACE_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_uri": "http://example.com",
"token_expires_in": 18000,
"token_uri": "{TOKEN_URI}",
"auth_uri": "{AUTH_URI}"
}
},
"relationships": {
"components": {
"data": [
{
"id": "{COMPONENT_ID}",
"type": "component"
}
]
},
"workspace": {
"data": {
"id": "{WORKSPACE_ID}",
"type": "workspace"
},
"links": {
"self": "/v2/workspaces/{WORKSPACE_ID}"
}
}
},
"links": {
"self": "/v2/auth-clients/{AUTH-CLIENT_ID}"
}
},
"meta": {}
}
This resource allows you to retrieve an Auth Client by its ID.
HTTP Request
GET https://api.elastic.io/v2/auth-clients/{AUTH-CLIENT_ID}
Authorization
This request is authorized with one of the global.auth_clients.get, tenants.auth_clients.get, contracts.auth_clients.get or workspaces.auth_clients.get. Each permission allows to get Auth Client in particular scope inclusively: global.auth_clients.get allows to get global client, tenants.auth_clients.get allows to get global and tenant’s client, contracts.auth_clients.get allows to get global, tenant’s and all tenant’s contracts clients, workspaces.auth_clients.get allows to get global, tenant’s, contracts’ and workspaces’ clients.
auth_clients.get permissions are also used to authorize access to Auth Client’s credentials field: one can see Auth Client’s credential only if client’s scope and permission’s scope match, i.e. credentials of tenant’s Auth Client are visible for users only with tenants.auth_clients.get permissions, though tenant Auth Client itself is visible for users with workspaces.auth_clients.get.
To specify scope of request one of workspace_id, contract_id or tenant_id query parameters is used. For example, tenant auth client can be retreived by id if user has workspaces.auth_clients.get permission in one of the tenant’s workspaces, so to specify those workspace workspace_id query parameter is used, without scope parameter you can get only global client. In case if the user tries to get not a global client and doesn’t specify the query parameter - such request will be rejected, as permission can’t be checked.
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| AUTH-CLIENT_ID | yes | Auth Client ID |
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| workspace_id | no | Show auth-client available in the given workspace (including global, tenant’s and contract’s auth-clients). |
| contract_id | no | Show auth-client available in the given contract (including global and tenant’s auth-clients). |
| tenant_id | no | Show auth-client available in the given tenant and global scopes. |
Returns
The Auth Client with given ID
Update the Auth Client
Example Request:
curl https://api.elastic.io/v2/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",
"credentials":{
"client_secret": "{CLIENT_SECRET}",
"token_expires_in": 18000
}
},
"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_uri": "http://example.com",
"token_expires_in": 18000,
"token_uri": "{TOKEN_URI}",
"auth_uri": "{AUTH_URI}"
}
},
"relationships":{
"components": {
"data": [
{
"id": "{COMPONENT_ID}",
"type": "component"
}
]
},
"tenant":{
"data":{
"id":"{TENANT_ID}",
"type":"tenant"
},
"links":{
"self":"/v2/tenants/{TENANT_ID}"
}
}
},
"links":{
"self":"/v2/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
name, token_expires_in 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/auth-clients/{AUTH-CLIENT_ID}
Authorization
This request is authorized for members with appropriate permission.
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| 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.client_secret | no | Auth Client client secret |
| attributes.credentials.token_expires_in | no | The value that will be set as expires_in in Auth Secret linked to the Auth Client after Auth Secret refresh if Auth Secret does not contain it. |
| 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/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/auth-clients/{AUTH-CLIENT_ID}
Authorization
This request is authorized for members with appropriate permission.
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| 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
Check Create a flow section on how to use a secret in your flow.
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":"ready",
"credentials":{
"access_token": "{ACCESS_TOKEN}",
"refresh_token": "{REFRESH_TOKEN}",
"expires_in": "{EXPIRES_IN}",
"additional_params": "{ADDITIONAL_PARAMS}"
}
},
"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":"ready",
"credentials":{
"access_token": "{ACCESS_TOKEN}",
"refresh_token": "{REFRESH_TOKEN}",
"expires_in": "{EXPIRES_IN}",
"additional_params": "{ADDITIONAL_PARAMS}"
}
},
"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, 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 | no | Auth Secret expires in. If not specified and auth-client is oauth2 then the value will be taken from token_expires_in of linked auth-client |
| attributes.credentials.additional_params | no (if auth-client is oauth2) |
Auth Secret additional parameters |
| 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}"
}
}
}
}'
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, 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 |
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
Accessing and sharing components
Each Component belongs to a Team. Each User who is a member of the team can edit the component.
The component has an attribute access, which indicates how is the component shared by the other clients. “Shared” means, that the component can be used by the users in their flows.
There are three sharing modes:
team– no sharing. Only Contract members can use the Component.tenant– 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,Webhooketc). Any Platform user can useglobalcomponents.
Accordingly, a set of components, available for each user is consist of: not shared components from the user’s Contract, components with tenant access and global components.
Retrieve all components
Example Request:
curl https://api.elastic.io/v2/components?contract_id={CONTRACT_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"{COMPONENT_ID}",
"type":"component",
"links":{
"self":"/v2/components/{COMPONENT_ID}"
},
"attributes":{
"name":"name",
"team_name":"team_name",
"access": "tenant"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{COMPONENT_ID}/versions"
}
},
"latest_version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/latest"
}
}
}
}
],
"meta":{},
"included":[
{
"id":"{GIT_REVISION}",
"type":"version",
"links":{
"self":"/v2/versions/{GIT_REVISION}"
},
"attributes":{
"date":1517392057184,
"version_number":69
},
"relationships":{
"descriptor":{
"data":{
"id":"0eff1d1a46b78ba1f468982e16d0382e8a91280d",
"type":"descriptor"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
}
},
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}"
}
}
}
},
{
"id":"0eff1d1a46b78ba1f468982e16d0382e8a91280d",
"type":"descriptor",
"links":{
"self":"/v2/descriptors/0eff1d1a46b78ba1f468982e16d0382e8a91280d"
},
"attributes":{
"repo_name":"repo_name",
"team_name":"team_name",
"short_revision":"0eff1d1",
"is_latest":true,
"description":"desc",
"icon":"BASE64",
"language":"nodejs",
"sailor_version":"2.1.6",
"title":"Data mapper",
"service":"mapper",
"actions":{
"map":{
"title":"Mapper",
"main":"./map.js"
},
"jsonataMap":{
"title":"Jsonata mapper",
"main":"./jsonata_map.js"
}
},
"fields":{
"mapper":{
"viewClass":"MapperView"
}
}
},
"relationships":{
"version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/{COMPONENT_ID}/versions/{GIT_REVISION}"
}
}
}
}
],
"links":{
"self":"/v2/components"
}
}
This endpoint retrieves a list of available components. Response includes latest descriptor for each component. More details about the component descriptors can be found here.
HTTP Request
GET https://api.elastic.io/v2/components?contract_id={CONTRACT_ID}
HTTP Request with parameters
GET https://api.elastic.io/v2/components?contract_id={CONTRACT_ID}&filter[access]=private
Query Parameters
| Parameter | Required | Description |
|---|---|---|
| contract_id | yes (only for Tenant Admin) | An Id of the Contract |
| filter[access] | No | Allowed values: private (only components from own Contract returned), public (only shared components from the other Contracts) and all (default value, returns all available components). |
Returns
Returns repositories metadata object if the call succeeded.
Retrieve a component by ID
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID} \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{COMPONENT_ID}",
"type":"component",
"links":{
"self":"/v2/components/{COMPONENT_ID}"
},
"attributes":{
"name":"component name",
"team_name":"{team_name}",
"access": "team"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{COMPONENT_ID}/versions"
}
},
"latest_version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/latest"
}
}
}
},
"meta":{},
"included":[
{
"id":"{GIT_REVISION}",
"type":"version",
"links":{
"self":"/v2/versions/{GIT_REVISION}"
},
"attributes":{
"date":1513183339032,
"version_number":7
},
"relationships":{
"descriptor":{
"data":{
"id":"{GIT_REVISION}",
"type":"descriptor"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
}
},
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}"
}
}
}
},
{
"id":"{GIT_REVISION}",
"type":"descriptor",
"links":{
"self":"/v2/descriptors/{GIT_REVISION}"
},
"attributes":{
"repo_name":"repo_name",
"team_name":"team_name",
"short_revision":"df7cf1d",
"is_latest":true,
"description":"desc",
"icon":"BASE64",
"language":"nodejs",
"sailor_version":"2.2.1",
"title":"title",
"actions":{
"update":"<Actions Object>"
},
"triggers":{
"select":"<Triggers Object>"
},
"credentials":{
"fields":{
"apiKey":{
"label":"API key",
"required":true,
"viewClass":"TextFieldWithNoteView",
"note":"{note}"
}
}
}
},
"relationships":{
"version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/{COMPONENT_ID}/versions/{GIT_REVISION}"
}
}
}
}
]
}
HTTP Request
GET https://api.elastic.io/v2/components/{COMPONENT_ID}
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| COMPONENT_ID | Yes | Component identifier |
Authorization
The component should be accessible to the client (e.g. component from the own Contract or shared one).
Returns
This endpoint returns a component object and includes latest descriptor for each component.
Retrieve component versions
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":[
{
"id":"{GIT_REVISION}",
"type":"version",
"links":{
"self":"/v2/versions/{GIT_REVISION}"
},
"attributes":{
"date":1508754889997,
"version_number":1
},
"relationships":{
"descriptor":{
"data":{
"id":"{GIT_REVISION}",
"type":"descriptor"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor"
}
},
"component":{
"data":{
"id":"{COMPONENT_ID}",
"type":"component"
},
"links":{
"self":"/v2/components/{COMPONENT_ID}"
}
}
}
}
],
"meta":{},
"links":{
"self":"/v2/components/{COMPONENT_ID}/versions"
}
}
This endpoint retrieves list of component’s versions
HTTP Request
GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| COMPONENT_ID | Yes | Component identifier |
Authorization
The component should be accessible to the client (e.g. component from the own Contract or shared one).
Returns
Returns repositories build metadata object if the call succeeded.
Retrieve a component descriptor
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{GIT_REVISION}",
"type":"descriptor",
"links":{
"self":"/v2/descriptors/{GIT_REVISION}"
},
"attributes":{
"repo_name":"repo_name",
"team_name":"team_name",
"short_revision":"cf0a2d9",
"is_latest":true,
"description":"desc",
"icon":"BASE64",
"language":"nodejs",
"sailor_version":"2.2.1",
"title":"title",
"actions":{
"update":"<Actions Object>"
},
"triggers":{
"select":"<Triggers Object>"
},
"credentials":{
"fields":{
"apiKey":{
"label":"API key",
"required":true,
"viewClass":"TextFieldWithNoteView",
"note":"note"
}
}
}
},
"relationships":{
"version":{
"data":{
"id":"{GIT_REVISION}",
"type":"version"
},
"links":{
"self":"/v2/{COMPONENT_ID}/versions/{GIT_REVISION}"
}
}
}
},
"meta":{}
}
This endpoint retrieves an information about single component by it’s ID and/or version,
for latest version use latest. More details can be find here.
HTTP Request
GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/descriptor
or
GET https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/latest/descriptor
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| COMPONENT_ID | Yes | Component identifier |
| GIT_REVISION | Yes | Revision of the component’s build. Use latest to retrieve the descriptor of the most recent successful build. |
Authorization
The component should be accessible for the client (e.g. component from own Contract or shared one).
Returns
Returns component descriptor if the call succeeded.
Create a component repository
Example Request:
curl https://api.elastic.io/v2/components/ \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"component",
"attributes":{
"name":"mycomponent"
},
"relationships":{
"team":{
"data":{
"type":"team",
"id":"{TEAM_ID}"
}
},
"contract":{
"data":{
"type":"contract",
"id":"{CONTRACT_ID}"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"{REPOSITORY_ID}",
"type":"component",
"links":{
"self":"/v2/components/{REPOSITORY_ID}"
},
"attributes":{
"name":"{REPOSITORY_NAME}",
"team_name":"{TEAM_NAME}",
"access": "team"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{REPOSITORY_ID}/versions"
}
}
}
},
"meta":{}
}
This resource allows you to create a component repository. A component repository always belongs to a team. If you don’t have any teams yet, please create a team first.
HTTP Request
POST https://api.elastic.io/v2/components
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value must be component |
| attributes.name | yes | Repository name |
| attributes.icon | no | Component icon as base64 string |
| relationships.team.data.id | yes | Team ID the repository to create for |
| relationships.team.data.type | yes | A value must be team |
| relationships.contract.data.id | no | Contract ID the repository to create for |
| relationships.contract.data.type | no | A value must be contract |
Authorization
This request is authorized to a user with contracts.repository.edit permission.
Returns
Returns component’s metadata object if the call succeeded.
Update component access
This resource allows you to changing component’s access level from team to tenant.
Please note, that this action is irreversible i.e. API does not allow to change access back to team.
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID} \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "component",
"attributes": {
"access": "tenant"
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{COMPONENT_ID}",
"type":"component",
"links":{
"self":"/v2/components/{COMPONENT_ID}"
},
"attributes":{
"name":"name",
"team_name":"team_name",
"access": "tenant"
},
"relationships":{
"versions":{
"links":{
"related":"/v2/components/{COMPONENT_ID}/versions"
}
}
}
},
"meta":{}
}
HTTP Request
PATCH https://api.elastic.io/v2/components/{COMPONENT_ID}
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| COMPONENT_ID | Yes | Component identifier |
Access level
A component may have one of the following access level:
team– no sharing. Only team members can use the component.tenant– component could be used by the other clients in the tenant.global– special mode for components from the standard set of components of the Platform (e.g.Timer,Webhooketc). Any user of the platform can useglobalcomponents.
Authorization
This request is authorized for a user with TenantAdmin role only. Contact support team to get this role.
Returns
Returns updated component’s metadata object if the call succeeded.
Delete a component
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID} \
-X DELETE \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 204 No Content
Content-Type: application/json
This resource allows you to delete a component. A component may only be delete if it not used in any flow.
HTTP Request
DELETE https://api.elastic.io/v2/components/{COMPONENT_ID}/
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| COMPONENT_ID | yes | Component ID |
Authorization
This request is authorized to a user with contracts.repository.edit permission. The component must belong to one of the client’s team.
Returns
204 HTTP response code if the call succeeds, error otherwise.
Retrieve component’s environment variables
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID}/env \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"attributes":{
"vars":{
"MY_ENV_VAR":"env_var_value"
}
},
"id":"{COMPONENT_ID}",
"type":"component-env",
"links":{
"self":"/v2/component-envs/{COMPONENT_ID}"
}
},
"meta":{}
}
This endpoint shows env vars for given component.
HTTP Request
GET https://api.elastic.io/v2/components/{COMPONENT_ID}/env
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| COMPONENT_ID | yes | Component ID |
Authorization
The component should be accessible to the client (e.g. component from the own team or shared one).
Returns
Returns environment variables
Update component’s environment variables
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID}/env \
-X PUT \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "component-env",
"attributes": {
"vars": {
"MY_ENV_VAR": "env_var_value"
}
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"attributes":{
"vars":{
"MY_ENV_VAR":"env_var_value"
}
},
"id":"{COMPONENT_ID}",
"type":"component-env",
"links":{
"self":"/v2/component-envs/{COMPONENT_ID}"
}
},
"meta":{}
}
This endpoint replaces env vars for given component.
HTTP Request
PUT https://api.elastic.io/v2/components/{COMPONENT_ID}/env
URL Parameters
| Parameter | Required | Description |
|---|---|---|
| COMPONENT_ID | yes | Component ID |
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value must be component-env |
| attributes.vars | yes | JSON object representing environmental variables mapped to their values. |
Authorization
The component should be accessible to the client (e.g. component from the own team or shared one).
Returns
Returns environment variables
Contracts
What is a Contract unit?
A Contract is a fundamental entity (scope) that reflects an agreement between a customer and the platform’s provider. The Contract scope can have an unlimited number of members, workspaces, and development teams. It also serves as a singular entity for the billing department against the consumed resources by all the integration flows. Every member of the Contract’s scope has a specific access level or role within the current Contract. To get all available roles, please execute the “Get the Contract’s roles” endpoint. The same user can have different roles in different Contracts within the Platform. Every Contract must have at least one Owner. The Owner’s Role has a predefined/default permissions’ set. It means this role cannot be deleted and the permissions’ set cannot be changed.
Please note that the Tenant Admin creates a Contract along with the Contract’s Owner. Once it’s done the Contract’s Owner will be able to invite other Users as well as assigning the necessary roles for them. (Tenant is a higher scope in the Platform’s hierarchy. It includes all the Contracts that belong to the white-label client).
Create a Contract
Example Request:
curl https://api.elastic.io/v2/contracts \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"contract",
"attributes":{
"name":"My Contract",
"available_roles":[
{
"scope":"contracts",
"role":"admin"
},
{
"scope":"workspaces",
"role":"admin"
}
]
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data":{
"id":"{CONTRACT_ID}",
"type":"contract",
"links":{
"self":"/v2/contracts/{CONTRACT_ID}"
},
"attributes":{
"name":"My Contract",
"available_roles":[
{
"role":"admin",
"scope":"contracts"
},
{
"role":"owner",
"scope":"contracts"
},
{
"role":"admin",
"scope":"workspaces"
},
{
"role":"owner",
"scope":"workspaces"
}
],
"status":"active"
}
},
"meta":{}
}
This endpoint allows creating a Contract.
HTTP Request
POST https://api.elastic.io/v2/contracts
Authorization
This request is authorized to only a user with TenantAdmin role. Contact support team to get this role.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “contract” |
| attributes.name | yes | Name of the Contract |
| attributes.available_roles[] | no | The subset of Tenants roles the particular Contract belongs to |
Returns
Returns Contract object if the call succeeded
Update a Contract
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID} \
-X PATCH \
-u {EMAIL}:{APIKEY} \
-H 'Content-Type: application/json' -d '
{
"data":{
"type":"contract",
"id":"{CONTRACT_ID}"
"attributes":{
"name":"New Contract Name",
"available_roles":[
{
"scope":"contracts",
"role":"admin"
},
{
"scope":"workspaces",
"role":"admin"
},
{
"scope":"workspaces",
"role":"guest"
}
]
}
}
}'
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"{CONTRACT_ID}",
"type":"contract",
"links":{
"self":"/v2/contracts/{CONTRACT_ID}"
},
"attributes":{
"name":"New Contract Name",
"available_roles":[
{
"role":"admin",
"scope":"contracts"
},
{
"role":"owner",
"scope":"contracts"
},
{
"role":"admin",
"scope":"workspaces"
},
{
"role":"guest",
"scope":"workspaces"
},
{
"role":"owner",
"scope":"workspaces"
}
],
"status":"active"
}
},
"meta":{}
}
This endpoint allows to change Contracts’ name and to update available roles in the Contract.
HTTP Request
PATCH https://api.elastic.io/v2/contracts/{CONTRACT_ID}
Authorization
For updating Contract name this request is authorized to the users with contracts.contract.edit permission. For updating the set of available roles of the particular Contract this request is authorized to the user with TenantAdmin role. Contact support team to get this role.
Payload Parameters
| Parameter | Required | Description |
|---|---|---|
| type | yes | A value should be “contract” |
| attributes.name | yes | Name of the Contract |
| attributes.available_roles[] | no | The subset of Tenants roles the particular Contract belongs to |
Returns
Returns Contract object if the call succeeded
Get Contract by Id
Example Request:
curl https://api.elastic.io/v2/contracts/{CONTRACT_ID}?include=members,invites \
-u {EMAIL}:{APIKEY}
Example Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"data":{
"id":"5b4f3e093a472b0006c71d47",
"type":"contract",
"links":{
"self":"/v2/contracts/5b4f3e093a472b06c71d47"
},
"attributes":{
"name":"LucontractOne",
"available_roles": [],
"status": "active"
},
"relationships":{
"members":{
"data":[
{
"id":"59d22eeb865b0018adc248",
"type":"contract-member"
},
{
"id":"5a1c298abe7a00189caf76",
"type":"contract-member"
}
],
"links":{
"self":"/v2/contracts/5b4f3e093a472b06c71d47/members/"
}
},
"invites":{
"data":[
{
"id":"5b6d8ce8033b0011fef43e",
"type":"contract-invite"
}
],
"links":{
"self":"/v2/contracts/5b4f3e093a4b0006c71d47/invites/"
}
}
}
},
"meta":{},
"included":[
{
"id":"59d22e7eebrr5b0018adc248",
"type":"contract-member",
"attributes":{
"first_name":"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
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 |
| 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":"components/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":"components/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,
"log_level": "info"
}
}
},
"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":"components/simple-trigger-component:timer@latest",
"name":"",
"description":"",
"selected_data_samples":[
"{DATA_SAMPLE_ID}"
]
},
{
"id":"step_2",
"component_id":"{COMPONENT_ID}",
"command":"components/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,
"log_level": "info"
}
},
"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.graph.nodes[].secret_id | no | Auth Secret ID to use for this step. It will be passed to a component action/trigger as a part of config |
| 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 |
| attributes.nodes_config.{STEP_ID}.log_level | no | Log level of component running in this step. Possible values are: trace, debug, info, warn, error, fatal, default: info |
| 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,
"log_level": "info"
}
}
}
}
}'
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,
"log_level": "info"
}
}
},
"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.graph.nodes[].secret_id | no | Auth Secret ID to use for this step. It will be passed to a component action/trigger as a part of config |
| 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 |
| attributes.nodes_config.{STEP_ID}.log_level | no | Log level of component running in this step. Possible values are: trace, debug, info, warn, error, fatal, default: info |
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":{
"type":"flow",
"id":"585918da586224001b96de89",
"links":{
"self":"/v2/flows/585918da586224001b96de89"
},
"attributes":{
"name":"this is a test task",
"status":"active",
"type":"ordinary",
"created_at":"2018-03-27T15:39:02.825Z",
"current_status":"inactive",
"default_mapper_type":"jsonata",
"description":null,
"updated_at":"2018-03-27T15:50:00.123Z",
"last_start_time":"2018-03-27T15:50:00.123Z",
"due_execution":"2018-03-27T15:53:00.123Z",
"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,
"log_level": "info"
}
}
},
"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 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
Returns the flow
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
Copy Flow (Experimental)
Endpoint provides possibility to copy flow. Flow can be copied in two modes:
- as new flow
- as a draft of existing flow
Modes are mutually exclusive (see example requests)
In both cases flow is copied into draft of new/existing flow. So to make flow to work draft should be published manually. That is done to avoid disruptions of already running flow (flow is not stopped or changed in any other way except draft), and because most likely flow copy will require additional configuration.
Flow can be copied in any workspace and contract, of course if user has enough privileges to read original flow and has enough privileges to edit flow in destination workspace.
Platform forbids to copy flow if flow components can not be used in destination context (e.g. component visibility is restricted to team, and you are copying flow in another contract)
Please note the following facts about credentials, secrets, topics and agents used in flow:
- All these entities are not copied along with the flow if they are not accessible in the destination context.
- Naturally, if the flow is copied into the same workspace, these entities will be accessible to the flow draft.
- Topic can be replaced during copy. Read details about
data.attributes.topic_idparameter.
Copy into existing flow example request:
curl https://api.elastic.io/v2/flows/{FLOW_ID}/copy \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "flow-copy",
"attributes": {
"dest_flow_id": "{DESTINATION_FLOW_ID}",
"name": "{DRAFT_NAME}",
"topic_id": "{TOPIC_ID}"
}
}
}'
Copy into new flow example request:
curl https://api.elastic.io/v2/flows/{FLOW_ID}/copy \
-X POST \
-u {EMAIL}:{APIKEY} \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' -d '
{
"data": {
"type": "flow-copy",
"attributes": {
"name": "{DRAFT_NAME}",
"topic_id": "{TOPIC_ID}"
},
"relationships": {
"dest_workspace": {
"data": {
"id": "{DESTINATION_WORKSPACE_ID}",
"type": "workspace"
}
}
}
}
}'
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":[],
"edges":[]
},
"nodes_config": {},
"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"
}
},
"draft": {
"data": {
"id": "{DRAFT_ID}",
"type": "flow-draft"
},
"links":{
"self":"/v2/flows/{FLOW_ID}/versions/{FLOW_VERSION_ID}",
"related":"/v2/flows/{FLOW_ID}/versions/{FLOW_VERSION_ID}"
}
}
}
},
"meta":{}
HTTP Request
POST https://api.elastic.io/v2/flows/{FLOW_ID}/copy
URL parameters
| Parameter | Required | Description |
|---|---|---|
| FLOW_ID | yes | source flow identifier |
Body Parameters
| Parameter | Required | Description |
|---|---|---|
| data.type | yes | The value must be flow-copy |
| data.attributes.dest_flow_id | yes | Destination flow identifier (dest_workspace should not be specified) |
| data.relationships.dest_workspace.data.id | yes | Destination workspace identifier (dest_flow_id should not be specified) |
| data.relationships.dest_workspace.data.type | yes | The value must be workspace |
| data.attributes.topic_id | no | Required only if flow contains Pub-Sub components. Only one topic reference allowed |
| data.attributes.name | no | Makes possible to customize name of the draft (and flow when new flow is created) |
Notices
- The topic (
data.attributes.topic_id) must be accessible to the flow in the destination workspace, otherwise it will not be copied. - It’s forbidden to use the
data.attributes.topic_idparameter if flow does not contain at least one step with Pub/Sub component. - It’s forbidden to use the
data.attributes.topic_idparameter if your flow uses more than one Pub/Sub topic in different steps. You can copy the flow if your flow has several Pub/Sub steps that uses only one topic. - In case when the
data.attributes.topic_idparameter is absent from your call, topics ID will be removed from a copy if it’s not accessible and left intact if the topic is available in destination context.
Authorization
- User should belong to workspace containing source flow.
- User should have
workspaces.flow.editpermission in destination workspace.
Returns
Returns created flow-draft or the draft for existing flow. If destination flow has the existing draft it will be overwritten.
Please notice once again: flow is copied as draft. So in response you may get empty flow (in copy into new flow mode) or old flow (in copy into exsising flow mode), as changes are done in draft, and draft is not included in response
Logs
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
Nonemeans 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)
Accessing and sharing recipes
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.
Create a recipe
Example Request:
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": {
"declarations": {
"variables": [
{
"id": "email",
"title": "Email address",
"help": {
"description": "Email to fill a \"CC\" field",
"link": "http://test.com/recipes/12345"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "Credentials to access your Petstore"
}
}
]
},
"info": {
"title": "My Recipe",
"author":"John Doe",
"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."
},
"flow_templates": [
{
"cron": "*/3 * * * *",
"title": "My first flow template",
"graph": {
"nodes": [
{
"id": "step_1",
"name": "Step name",
"credentials_id": "petstore",
"description": "Step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"dynamic_metadata": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "step_2",
"name": "Step name",
"description": "Step description",
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"dontThrowErrorFlg": true
},
"dynamic_select_model": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "error_all",
"name": "Error handler",
"error": true,
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"data_sample": {
"foo": "bar"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"to": "pets[0].name",
"cc": "$getFlowVariables().email",
"subject": "pets[0].id",
"textBody": "pets[0].status"
},
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"target": "error_all"
}
]
}
}
]
},
"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",
"visibility": "workspace",
"links": {
"self": "/v2/recipes/{RECIPE_ID}"
},
"attributes": {
"declarations": {
"variables": [
{
"id": "email",
"title": "Email address",
"help": {
"description": "Email to fill a \"CC\" field",
"link": "http://test.com/recipes/12345"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "Credentials to access your Petstore"
}
}
]
},
"info": {
"title": "My Recipe",
"author":"John Doe",
"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."
},
"flow_templates": [
{
"cron": "*/3 * * * *",
"title": "My first flow template",
"graph": {
"nodes": [
{
"id": "step_1",
"name": "Step name",
"credentials_id": "petstore",
"description": "Step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"dynamic_metadata": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "step_2",
"name": "Step name",
"description": "Step description",
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"dontThrowErrorFlg": true
},
"dynamic_select_model": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "error_all",
"name": "Error handler",
"error": true,
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"data_sample": {
"foo": "bar"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"to": "pets[0].name",
"cc": "$getFlowVariables().email",
"subject": "pets[0].id",
"textBody": "pets[0].status"
},
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"target": "error_all"
}
]
}
}
]
},
"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}"
}
}
}
}
}
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.declarations.variables[] | no | List of variables used by steps in a flow |
| attributes.declarations.credentials[] | no | List of credentials used by steps in a flow |
| attributes.info.title | yes | Recipe title |
| attributes.info.author | no | Recipe author name which replaces recipe creator |
| attributes.info.description | yes | Recipe description |
| attributes.info.short_description | yes | Recipe short description |
| attributes.flow_templates[].title | yes | Flow template title |
| attributes.flow_templates[].cron | no | Cron expression |
| attributes.flow_templates[].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": {
"dest_workspace": {
"data": {
"type": "workspace",
"id": "{WORKSPACE_ID}"
}
}
}
}
}'
Example Response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"data": {
"id": "{RECIPE_ID}",
"type": "recipe",
"visibility": "workspace",
"links": {
"self": "/v2/recipes/{RECIPE_ID}"
},
"attributes": {
"declarations": {
"variables": [
{
"id": "email",
"title": "Email address",
"help": {
"description": "Email to fill a \"CC\" field",
"link": "http://test.com/recipes/12345"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "Credentials to access your Petstore"
}
}
]
},
"info": {
"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."
},
"flow_templates": [
{
"cron": "*/3 * * * *",
"title": "My first flow template",
"graph": {
"nodes": [
{
"id": "step_1",
"name": "Step name",
"credentials_id": "petstore",
"description": "Step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"dynamic_metadata": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "step_2",
"name": "Step name",
"description": "Step description",
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"dontThrowErrorFlg": true
},
"dynamic_select_model": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "error_all",
"name": "Error handler",
"error": true,
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"data_sample": {
"foo": "bar"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"to": "pets[0].name",
"cc": "$getFlowVariables().email",
"subject": "pets[0].id",
"textBody": "pets[0].status"
},
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"target": "error_all"
}
]
}
}
]
},
"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}"
}
}
}
}
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 and workspaces.flow.exportToRecipe permissions
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",
"visibility": "workspace",
"links": {
"self": "/v2/recipes/{RECIPE_ID}"
},
"attributes": {
"declarations": {
"variables": [
{
"id": "email",
"title": "Email address",
"help": {
"description": "Email to fill a \"CC\" field",
"link": "http://test.com/recipes/12345"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "Credentials to access your Petstore"
}
}
]
},
"info": {
"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."
},
"flow_templates": [
{
"cron": "*/3 * * * *",
"title": "My first flow template",
"graph": {
"nodes": [
{
"id": "step_1",
"name": "Step name",
"credentials_id": "petstore",
"description": "Step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"dynamic_metadata": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "step_2",
"name": "Step name",
"description": "Step description",
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"dontThrowErrorFlg": true
},
"dynamic_select_model": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "error_all",
"name": "Error handler",
"error": true,
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"data_sample": {
"foo": "bar"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"to": "pets[0].name",
"cc": "$getFlowVariables().email",
"subject": "pets[0].id",
"textBody": "pets[0].status"
},
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"target": "error_all"
}
]
}
}
]
},
"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}"
}
}
}
}
}
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",
"visibility": "workspace",
"links": {
"self": "/v2/recipes/{RECIPE_ID}"
},
"attributes": {
"declarations": {
"variables": [
{
"id": "email",
"title": "Email address",
"help": {
"description": "Email to fill a \"CC\" field",
"link": "http://test.com/recipes/12345"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "Credentials to access your Petstore"
}
}
]
},
"info": {
"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."
},
"flow_templates": [
{
"cron": "*/3 * * * *",
"title": "My first flow template",
"graph": {
"nodes": [
{
"id": "step_1",
"name": "Step name",
"credentials_id": "petstore",
"description": "Step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"dynamic_metadata": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "step_2",
"name": "Step name",
"description": "Step description",
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"dontThrowErrorFlg": true
},
"dynamic_select_model": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "error_all",
"name": "Error handler",
"error": true,
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"data_sample": {
"foo": "bar"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"to": "pets[0].name",
"cc": "$getFlowVariables().email",
"subject": "pets[0].id",
"textBody": "pets[0].status"
},
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"target": "error_all"
}
]
}
}
]
},
"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": 1,
"total": 16,
"total_pages": 16
}
}
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": {
"info": {
"title": "My simple recipe",
"author": "AUTHOR OF RECIPE",
"short_description": "Recipe of integration flow",
"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**."
},
"declarations": {
"variables": [
{
"id": "petStatus",
"title": "Status of the pet to create",
"help": {
"description": "Every pet in our store needs a status. Please enter your favourite status.",
"link": "http://some.helplink.com"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "We need your credentials from your Petstore to export the pets"
}
}
]
},
"flow_templates": [
{
"title": "Create a cuddly pet",
"graph": {
"nodes": [
{
"name": "step 1",
"description": "step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"status": "petStatus"
},
"error": false,
"id": "step_1",
"credentials_id": "petstore",
"data_sample": {
"pets": [
{
"id": 10,
"status": "pending",
"name": "Dolly",
"category": {
"id": 2,
"name": "cats"
}
},
{
"id": 11,
"status": "pending",
"name": "Gorilla",
"category": {
"id": 1,
"name": "dogs"
}
}
]
},
"dynamic_select_model": {
"getStatusModel": {
"sold": "Sold",
"pending": "Pending",
"available": "Available"
}
}
},
{
"name": "step 2",
"description": "ololool",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"fields": {},
"error": false,
"id": "step_2",
"credentials_id": "petstore",
"data_sample": {
"newDynamicField": 10,
"status": "pending",
"name": "Dolly"
},
"dynamic_metadata": "{\"in\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\",\"required\":true,\"title\":\"Name\"},\"status\":{\"type\":\"string\",\"required\":true,\"title\":\"Status\"},\"newDynamicField\":{\"type\":\"string\",\"required\":true,\"title\":\"New dynamic field\"}}},\"out\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\",\"required\":true,\"title\":\"Name\"},\"status\":{\"type\":\"string\",\"required\":true,\"title\":\"Status\"},\"newDynamicField\":{\"type\":\"string\",\"required\":true,\"title\":\"New dynamic field\"}}}}"
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": "{\n \"name\": pets[0].name,\n \"status\": pets[0].status,\n \"newDynamicField\": pets[0].id\n}",
"condition": null
},
"source": "step_1",
"target": "step_2"
}
]
}
},
{
"title": "Flow with error handler",
"graph": {
"nodes": [
{
"name": "Get Pets",
"description": "by status",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"status": "available"
},
"error": false,
"id": "step_1",
"credentials_id": "petstore",
"data_sample": {
"pets": [
{
"id": 1,
"status": "available",
"name": "Brownie",
"category": {
"id": 1,
"name": "dogs"
}
},
{
"id": 2,
"status": "available",
"name": "Doggie",
"category": {
"id": 1,
"name": "dogs"
}
}
]
}
},
{
"name": "Create pet",
"description": "with promise",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"fields": {},
"error": false,
"id": "step_2",
"credentials_id": "petstore",
"data_sample": {
"name": "Brownie",
"status": "available"
}
},
{
"name": "Error Handler",
"description": "catch error",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"fields": {},
"error": true,
"id": "error_all",
"credentials_id": "petstore",
"data_sample": {
"name": "{\"name\":\"Error name\",\"message\":\"Error message\",\"stack\":\"Error stack trace\"}",
"status": "sold"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": "{\n \"name\": pets[0].name,\n \"status\": pets[0].status\n}",
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"status": "\"sold\"",
"name": "ErrorMessage"
},
"condition": null,
"error": true
},
"source": null,
"target": "error_all"
}
]
}
}
]
}
}
}'
Example response
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {
"id": "{RECIPE_ID}",
"type": "recipe",
"visibility": "workspace",
"links": {
"self": "/v2/recipes/{RECIPE_ID}"
},
"attributes": {
"declarations": {
"variables": [
{
"id": "email",
"title": "Email address",
"help": {
"description": "Email to fill a \"CC\" field",
"link": "http://test.com/recipes/12345"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "Credentials to access your Petstore"
}
}
]
},
"info": {
"title": "My Recipe",
"author":"John Doe",
"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."
},
"flow_templates": [
{
"cron": "*/3 * * * *",
"title": "My first flow template",
"graph": {
"nodes": [
{
"id": "step_1",
"name": "Step name",
"credentials_id": "petstore",
"description": "Step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"dynamic_metadata": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "step_2",
"name": "Step name",
"description": "Step description",
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"dontThrowErrorFlg": true
},
"dynamic_select_model": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "error_all",
"name": "Error handler",
"error": true,
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"data_sample": {
"foo": "bar"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"to": "pets[0].name",
"cc": "$getFlowVariables().email",
"subject": "pets[0].id",
"textBody": "pets[0].status"
},
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"target": "error_all"
}
]
}
}
]
},
"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}"
}
}
}
}
}
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 |
|---|---|---|
| id | yes | Recipe Id must be same as url parameter |
| type | yes | A value must be recipe |
| attributes.declarations.credentials[] | no | List of credentials used by steps in a flow |
| attributes.declarations.variables[] | no | List of variables used by steps in a flow |
| attributes.info.title | no | Recipe title |
| attributes.info.author | no | Recipe author name which replaces recipe creator |
| attributes.info.description | no | Recipe description |
| attributes.info.short_description | no | Recipe short description |
| attributes.flow_templates[].cron | no | Cron expression |
| attributes.flow_templates[].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 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",
"visibility": "contract",
"links": {
"self": "/v2/recipes/{RECIPE_ID}"
},
"attributes": {
"declarations": {
"variables": [
{
"id": "email",
"title": "Email address",
"help": {
"description": "Email to fill a \"CC\" field",
"link": "http://test.com/recipes/12345"
}
}
],
"credentials": [
{
"id": "petstore",
"help": {
"description": "Credentials to access your Petstore"
}
}
]
},
"info": {
"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."
},
"flow_templates": [
{
"cron": "*/3 * * * *",
"title": "My first flow template",
"graph": {
"nodes": [
{
"id": "step_1",
"name": "Step name",
"credentials_id": "petstore",
"description": "Step description",
"command": "elasticio/petstore:getPetsByStatusWithGenerators@bfa02ebf35383d98e2099b0a791a755a",
"dynamic_metadata": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "step_2",
"name": "Step name",
"description": "Step description",
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"fields": {
"dontThrowErrorFlg": true
},
"dynamic_select_model": {
"field": "value"
},
"data_sample": {
"foo": "bar"
}
},
{
"id": "error_all",
"name": "Error handler",
"error": true,
"command": "elasticio/email:send@bfa02ebf35383d98e2099b0a791a755a",
"data_sample": {
"foo": "bar"
}
}
],
"edges": [
{
"config": {
"mapper_type": "jsonata",
"mapper": {
"to": "pets[0].name",
"cc": "$getFlowVariables().email",
"subject": "pets[0].id",
"textBody": "pets[0].status"
},
"condition": null
},
"source": "step_1",
"target": "step_2"
},
{
"target": "error_all"
}
]
}
}
]
},
"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}"
}
}
}
}
}
This resource allows you to update attribute visibility of the given recipe. You can upgrade or downgrade recipe visibility.
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
tenantif user has permissiontenant.recipe.edit_visibility_tenantto
globalif user has permissionglobal.recipe.edit_visibility_globalto
contractif user has permissionworkspaces.recipe.editto
workspaceif user has permissionworkspaces.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": {
"credentials": {
"step_1": "{CREDENTIAL_ID}"
},
"variables": {
"TO_EMAIL": "goose@example.com",
"NAME_IN_SUBJECT": "Neochen Jubata"
}
},
"relationships": {
"workspace": {
"data": {
"type": "workspace",
"id": "{WORKSPACE_ID}"
}
}
}
}
}'
Example response
HTTP/1.1 201 Created
{
"data": {
"relationships": {
"flows": [
{
"data": {
"type": "flow",
"id": "{FLOW_ID}"
}
}
]
}
}
}
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.credentials | yes | Specify values for credentials used by steps in a flow |
| attributes.variables | yes | Specify values for variables which were defined in Recipe for mapping |
| 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 204 Ok
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:
selectModelallows retrieving available options for certain parameter of configuration, when component/module is used in some node in some flowgetMetaModelallows retrieving metadata for certain configuration of some node of some flowverifyCredentialsallows verifying if a configuration of credential of a certain component is valid
Each of the methods is executed in the same environment as a module of a component while executing of flows.
Scheduled execution workflow
A component execution is an asynchronous operation. Upon an client request an execution is scheduled and needs to wait for the next available worker. Once a worker is available the component is executed and the results are sent back to the client. Because the results of an execution cannot be created and returned immediately the client needs to wait and poll for the results.
For more details about asynchronous REST please read RESTful CookBook and A day in the life of - Asynchronous operations in REST.
The following diagram displays the process of component scheduling:
- A method execution is scheduled by sending a request corresponding endpoint (see below). The API responds with
202 Accepted. The resource in theLocationHTTP header is the URL to poll for execution results. - The execution result is polled periodically by sending requests to the polling resource
exec/poll/{EXECUTION_ID}. The API responds with200 OKif the result is not available yet. Please see how to poll execution results. - Once the result is available the polling resource responds with
303 See Other. The resource in theLocationHTTP header is the URL to get the results of the execution. Please see how to poll execution results. - The results are retrieved from
exec/result/{EXECUTION_ID}. Please see how to retrieve execution results.
Verify credentials
Example Request:
curl https://api.elastic.io/v2/components/{COMPONENT_ID}/versions/{GIT_REVISION}/verify-credential \
-u {EMAIL}:{APIKEY} \
-X POST -H 'Content-Type: application/json' -d '
{
"data":{
"type":"verify-credential",
"attributes":{
"fields":{
"apiKey":"api_secret"
}
},
"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"
]
},
"feature_flags":{
"old_mapper_enabled":false
}
}
}
}`
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"
]
},
"feature_flags":{
"old_mapper_enabled":false
}
}
},
"meta":{}
}
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 fullor limited depending on Tenant settings. |
| attributes.html_meta.description | no | Customer meta description in html pages |
| attributes.html_meta.author | no | Customer meta author in html pages |
| attributes.html_meta.keywords | no | Customer meta keywords in html pages |
| attributes.feature_flags.old_mapper_enabled | no | Enable ability to use deprecated mapper UI. Default: “false” |
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"
}
],
"feature_flags":{
"old_mapper_enabled":false
}
}
}
}'
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"
}
]
}
],
"feature_flags":{
"old_mapper_enabled":false
}
},
"meta":{}
}
}
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 |
| attributes.feature_flags.old_mapper_enabled | no | Enable ability to use deprecated mapper UI. Default: “false” |
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"
}
]
}
],
"feature_flags":{
"old_mapper_enabled":false
}
},
"meta":{},
}
]
}
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"
}
]
}
],
"feature_flags":{
"old_mapper_enabled":false
}
}
},
"meta":{}
}
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.devTeam.edit",
"contracts.membership.edit",
"contracts.repository.edit",
"contracts.workspace.create",
"contracts.workspace.delete",
"contracts.workspace.listAll",
"contracts.workspace_limits.edit",
"global.auth_clients.create",
"global.auth_clients.delete",
"global.auth_clients.edit",
"global.auth_clients.get",
"workspaces.auth_secret.create",
"workspaces.auth_secret.delete",
"workspaces.auth_secret.edit",
"workspaces.auth_secret.get",
"workspaces.auth_secret.get_credentials",
"workspaces.auth_secret.refresh",
"workspaces.credential.edit",
"workspaces.flow.edit",
"workspaces.flow.exportToRecipe",
"workspaces.flow.toggleRealtime",
"workspaces.flow.toggleStatus",
"workspaces.logs.read_all",
"workspaces.recipe.edit",
"workspaces.topic.create",
"workspaces.topic.delete",
"workspaces.topic.edit",
"workspaces.topic.get",
"workspaces.vpn_agent.create",
"workspaces.vpn_agent.delete",
"workspaces.vpn_agent.edit",
"workspaces.vpn_agent.get",
"workspaces.vpn_agent.get_config",
"workspaces.workspace.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 | |
| 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).