Skip to main content
Version: 2.4.1

API

API docs by Redocly

Resoto Core REST API (V1)

Download OpenAPI specification:Download

Search the graph and return all nodes as list (this will not contain any edges)

Search the graph and return the matching nodes as list. A section can be defined (defaults to / == root) to interpret relative property paths. Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

query Parameters
section
string
Enum: "reported" "desired" "metadata"

The name of the section used for all property paths. If not defined root is assumed.

count
boolean
Default: true

Optional parameter to get a Ck-Element-Count header which returns the number of returned json elements

Request Body schema: text/plain

The search to perform

string

Responses

Response samples

Content type
[
  • {
    }
]

Search the graph and return the resulting graph.

Search the graph and return the matching nodes including the traversed edges. The resulting data can be interpreted as a graph. A section can be defined (defaults to / == root) to interpret relative property paths. Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

query Parameters
section
string
Enum: "reported" "desired" "metadata"

The name of the section used for all property paths. If not defined root is assumed.

count
boolean
Default: true

Optional parameter to get a Ck-Element-Count header which returns the number of returned json elements

search_timeout
string
Example: search_timeout=30s

Optional duration the search is allowed to run.

Request Body schema: text/plain

The search to perform

string

Responses

Response samples

Content type
[
  • {
    }
]

Search the aggregate function on the specified graph and return the aggregation result.

Search and aggregate the graph and return the resulting aggregated data. A section can be defined (defaults to / == root) to interpret relative property paths. Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

query Parameters
section
string
Enum: "reported" "desired" "metadata"

The name of the section used for all property paths. If not defined root is assumed.

Request Body schema: text/plain

The aggregation search to perform

string

Responses

Response samples

Content type
"[\n { \"count\": 60, \"kind\": \"aws_ec2_instance_type\", \"mem_avg\": 28.45, \"mem_max\": 64, \"mem_min\": 1, \"mem_total\": 1707 },\n { \"count\": 105686, \"kind\": \"gcp_machine_type\", \"mem_avg\": 213.57744392143945, \"mem_max\": 3844, \"mem_min\": 0.599609375, \"mem_total\": 22572145.73828125 }\n]\n"

Explain the search execution plan

Explain the runtime characteristics of a search without performing the search. A section can be defined (defaults to / == root) to interpret relative property paths. Example: is(volume) and (reported.age>23d or desired.clean==true or metadata.version==2)

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

query Parameters
section
string
Enum: "reported" "desired" "metadata"

The name of the section used for all property paths. If not defined root is assumed.

Request Body schema: text/plain

The search to perform

string

Responses

Response samples

Content type
application/json
{
  • "estimated_cost": 0,
  • "estimated_nr_items": 0,
  • "available_nr_items": 0,
  • "full_collection_scan": true,
  • "rating": "simple"
}

graph_management

Create, update wipe or delete a complete graph.

List all graphs

Responses

Response samples

Content type
application/json
[
  • "main",
  • "test"
]

Get root of a specific graph

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

Responses

Response samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

Create a new graph

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

Responses

Response samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

Delete an existing graph

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

query Parameters
truncate
boolean

If this parameter is set, leave the graph definition, but wipe the data.

Responses

Response samples

Content type
text/plain
Graph deleted.

Merge a given graph with the existing graph under marked merge nodes.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

Request Body schema: application/x-ndjson

The graph is sent as newline delimited json, where each line holds a document, which is either a node or an edge.

One of
id
string

The identifier of this node.

type
string
object (Node)
object
object

Responses

Request samples

Content type
application/x-ndjson
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "nodes_created": 0,
  • "nodes_updates": 0,
  • "nodes_deleted": 0,
  • "edges_created": 0,
  • "edges_updated": 0,
  • "edges_deleted": 0
}

Merge a given graph with the existing graph under marked merge nodes as batch update.

Experimental: This API is not stable and might be subject of change.
Merge a given graph with the existing graph under marked merge nodes as batch update.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

query Parameters
batch_id
string
Default: null

A batch identifier is a string that uniquely identifies the batch update. If this parameter is omitted, a new batch identifier is created automatically. The resulting batch identifier can be retrieved via the response message.

Request Body schema: application/x-ndjson

The graph is sent as newline delimited json, where each line holds a document, which is either a node or an edge.

One of
id
string

The identifier of this node.

type
string
object (Node)
object
object

Responses

Request samples

Content type
application/x-ndjson
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "nodes_created": 0,
  • "nodes_updates": 0,
  • "nodes_deleted": 0,
  • "edges_created": 0,
  • "edges_updated": 0,
  • "edges_deleted": 0
}

Get a list of all running batch updates

Experimental: This API is not stable and might be subject of change.
Get a list of all running batch updates.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Commit a batch update

Experimental: This API is not stable and might be subject of change.
Commit a batch update.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

batch_id
required
string

A batch identifier is a string that uniquely identifies the batch update.

Responses

Response samples

Content type
application/json
"Batch committed."

Abort a batch update

Experimental: This API is not stable and might be subject of change.
Abort a batch update.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

batch_id
required
string

A batch identifier is a string that uniquely identifies the batch update.

Responses

Response samples

Content type
application/json
"Batch aborted."

node_management

Create, update, delete and get a node in the graph.

Patch a list of nodes.

Apply a patch on existing nodes. Non existing nodes are not updated! Consider to stream the request body as new line delimited json (application/x-ndjson).

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

Request Body schema:

The partial object data to patch.

id
string

The identifier of the node.

object
object
object

Responses

Request samples

Content type
{
  • "id": "string",
  • "reported": { },
  • "desired": { },
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

Create a new node under the given parent node

Experimental: This API is not stable and might be subject of change.
Create a new node under the given parent node.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

node_id
required
string

The identifier of the node

parent_node_id
required
string

The identifier of the parent node

Request Body schema: application/json

The node document to create.

kind
string

The kind of this node.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

Response samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

Get a node with the given node id

Experimental: This API is not stable and might be subject of change.
Get a node with the given node id

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

node_id
required
string

The identifier of the node

Responses

Response samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

Update a node with the given node id

Experimental: This API is not stable and might be subject of change.
Update a node with the given node id

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

node_id
required
string

The identifier of the node

Request Body schema: application/json

The partial object data to patch.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

Delete a node with the given node id.

Experimental: This API is not stable and might be subject of change.
Delete a node with the given node id.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

node_id
required
string

The identifier of the node

Responses

Patch a node with the given node id in given section

Experimental: This API is not stable and might be subject of change.
Patch a node with the given node id in given section

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

node_id
required
string

The identifier of the node

section
required
string
Enum: "reported" "desired" "metadata"

The identifier of the section

Request Body schema: application/json

The partial object data to patch.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "kind": "test.person",
  • "name": "Batman",
  • "city": "Gotham"
}

model

Endpoints to maintain the schema and model of the entities inside a graph.

Get the currently defined model.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Add or update the current defined model.

Request Body schema: application/json

Complete model or part of the model.

Array
One of
min_length
string

The minimal length of this string

max_length
string

The maximal length of this string

pattern
string

The regexp pattern, that this string has to adhere to

enum
Array of strings

The allowed values of this string enumerated here

runtime_kind
string
Enum: "string" "int32" "int64" "float" "double" "boolean" "date" "datetime"

The runtime kind of this kind

fqn
string

The fully qualified name of the kind

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get the currently defined model as svg uml image.

query Parameters
output
string
Default: "svg"
Enum: "svg" "png"

The output format.

show
string
Example: show=aws_ec2_instance,gcp.*

comma separated list of resources to show. Entries can be regexps.

hide
string
Example: hide=aws_ec2_instance,gcp.*

comma separated list of resources to hide. Entries can be regexps. hide takes precedence over show.

with_inheritance
boolean
Default: true

Include inheritance relations in the model.

with_base_classes
boolean
Default: true

Include all base classes of visible entries

with_subclasses
boolean
Default: false

Include all descendant classes of visible entries

dependency
string
Example: dependency=default

comma separated list of dependency relationships.

with_predecessors
boolean
Default: false

Include all predecessors of selected entries

with_successors
boolean
Default: false

Include all successors of selected entries

with_properties
boolean
Default: true

Show properties of selected entries

link_classes
boolean
Default: false

Add anchor links to classes.

Responses

config

Endpoints to maintain configuration data.

Get all configuration keys

Experimental: This API is not stable and might be subject of change.
Get all configuration keys in the system.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get a configuration by its id

Experimental: This API is not stable and might be subject of change.
Fetch a configuration by id.

path Parameters
config_id
required
string

the identifier of the config to get.

Responses

Response samples

Content type
application/json
{ }

Replace a configuration with given id

Experimental: This API is not stable and might be subject of change.
Replace a configuration identified by id with provided value.

path Parameters
config_id
required
string

the identifier of the config to get.

query Parameters
validate
boolean

This parameter can be used to turn off config validation. In case it is not defined or not set to false, every configuaration value is validated.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Patch a configuration by its id

Experimental: This API is not stable and might be subject of change.
Patch a configuration identified by id with provided value.

path Parameters
config_id
required
string

the identifier of the config to get.

Request Body schema: application/json
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Delete a configuration by its id

Experimental: This API is not stable and might be subject of change.
Delete a configuration identified by id with provided value.

path Parameters
config_id
required
string

the identifier of the config to get.

Responses

config_validation

Endpoints to define how configs should be validated.

Get the currently defined configuration model.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Add or update the current defined configuration model.

Request Body schema: application/json

Complete model or part of the model.

Array
One of
min_length
string

The minimal length of this string

max_length
string

The maximal length of this string

pattern
string

The regexp pattern, that this string has to adhere to

enum
Array of strings

The allowed values of this string enumerated here

runtime_kind
string
Enum: "string" "int32" "int64" "float" "double" "boolean" "date" "datetime"

The runtime kind of this kind

fqn
string

The fully qualified name of the kind

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get all configuration keys that have a model defined.

Experimental: This API is not stable and might be subject of change.
Get all configuration keys that have a model defined.

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get a configuration by its id

Experimental: This API is not stable and might be subject of change.
Fetch the model of a configuration by id.

path Parameters
config_id
required
string

the identifier of the config.

Responses

Response samples

Content type
{
  • "id": "string",
  • "external_validation": true
}

Replace a configuration model with given id

Experimental: This API is not stable and might be subject of change.
Replace a configuration model identified by id with provided value.

path Parameters
config_id
required
string

the identifier of the config to get.

Request Body schema: application/json
id
string

The identifier of the related configuration.

external_validation
boolean

True, if an external entity should validate a config change. In this case resotocore is emitting a task on the task queue of type validate_config. It expectes a listener to pickup this task and report back, if the configuration is valid or not.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "external_validation": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "external_validation": true
}

cli

Endpoints to evaluate and execute cli commands.

Evaluate a cli command

This method can be used to analyze if the command can be interpreted without executing it. When this method returns a 200 OK, the command can be parsed and evaluated.

query Parameters
object

All search parameter form the environment passed to the CLI interpreter.

Request Body schema: text/plain

The command will be sent as request body. A command can contain multiple command line separated by semicolon. Every single line can contain multiple commands that are combined via the pipe operator.

string

Responses

Response samples

Content type
application/json
[
  • { }
]

Execute a cli command

The body defines the command to execute. The command is executed and the result is returned to the client. Request and execution are synchronized: the request is done, when the command is done.

query Parameters
object

All search parameter form the environment passed to the CLI interpreter.

Request Body schema: text/plain

The command will be sent as request body. A command can contain multiple command line separated by semicolon. Every single line can contain multiple commands that are combined via the pipe operator.

string

Responses

Response samples

Content type
[
  • { }
]

Get information about CLI

Experimental: This API is not stable and might be subject of change.
Get information about CLI

Responses

Response samples

Content type
application/json
{
  • "commands": [
    ],
  • "replacements": {
    },
  • "alias_names": {
    },
  • "alias_templates": [
    ]
}

subscriptions

Endpoints to manipulate event subscriptions.

List all subscriptions

Get all subscriptions of all subscribers in the system

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List all subscribers for a given event type

Get all subscriptions of registered subscribers

path Parameters
event_type
required
string

The type of message

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get subscriber by id

Get the subscriber with a defined id.

path Parameters
subscriber_id
required
string

The identifier of the subscriber

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "subscriptions": {
    }
}

Define subscriber with all subscriptions

Define or redefine a subscriber with all subscriptions. In case the subscriber does not exist, it is created. In case the subscriber exist, all subscriptions get replaced.

path Parameters
subscriber_id
required
string

The identifier of the subscriber

Request Body schema: application/json

The list of all subscriptions.

Array
message_type
string

The name of the action to listen to

wait_for_completion
boolean
Default: true

If an action is sent to this subscriber, the event sender should wait until this subscriber has processed the message and send a done message. This is the expected behaviour of every actor and defaults to true.

timeout
number
Default: 60

This is the duration in seconds this subscriber has time to execute the action. After this time the sender assumes a failure and rejects the result of this actor.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "id": "string",
  • "subscriptions": {
    }
}

Delete by id

Delete the subscriber with a defined id.

path Parameters
subscriber_id
required
string

The identifier of the subscriber

Responses

Add subscription to subscriber

Add a specific subscription to a subscriber.

path Parameters
subscriber_id
required
string

The identifier of the subscriber

event_type
required
string

The action event type.

query Parameters
timeout
number
Default: 60

This is the duration in seconds this subscriber has time to execute the action. After this time the sender assumes a failure and rejects the result of this actor.

wait_for_completion
boolean
Default: true

If an action is sent to this subscriber, the event sender should wait until this subscriber has processed the message and send a done message. This is the expected behaviour of every actor and defaults to true.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "subscriptions": {
    }
}

Delete a specific subscription from the subscriber.

Delete a specific subscription from the subscriber.

path Parameters
subscriber_id
required
string

The identifier of the subscriber

event_type
required
string

The action event type.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "subscriptions": {
    }
}

[WebSocket] Listen to registered events of given subscriber

WebSocket Endpoint

The client needs to send all the required headers for a ws connection and has to handle the websocket protocol.
Note this can not be tested from within swagger!

The connection to this endpoint will never be closed. All action events of the system this subscriber has registerd will be send to this connection.

path Parameters
subscriber_id
required
string

The identifier of the subscriber

Responses

work_queue

Endpoints to attach to the work queue.

[WebSocket] Attach to the working queue

WebSocket Endpoint

The client needs to send all the required headers for a ws connection and has to handle the websocket protocol.
Note this can not be tested from within swagger!

This endpoint is used by worker nodes which can perform work. A worker would use this endpoint to establish a websocket connection and register the tasks that can be performed by the worker. One worker can perform one or more tasks over one connection.

In case the connection is lost, all outstanding tasks are rescheduled to other workers. This means the local tasks queue should be wiped in case of connection loss.

Note: the server tries to spread the number of tasks evenly over the number of workers. This number is derived by the number of outstanding messages in the queue irrelevant which tasks are outstanding.

query Parameters
task
Array of strings

The name of all tasks that this worker is able to perform.

object
Example: cloud=aws&account=123,124,125

Additional properties to filter tasks of provided task name. The value of the parameter is either a string or a list of strings separated by comma. The available filter criteria are defined by the specific task to execute.

All specified filter criteria need to match by the task to execute. If a list of values is defined for a filter criteria, at least one needs to match. (e.g. cloud=aws,gcp would match a task for cloud=aws).

Example: The worker is able to perform tasks of type tag, but only for cloud AWS: cloud=aws

     The worker is able to perform tasks of type tag, for AWS and GCP:
     cloud=aws,gcp

     Maybe the worker is only capable to perform the work in a specific account.
     cloud=aws&account=123 could be specified to only filter for tasks in this cloud in this
     account.

In case there are multiple workers that match the task criteria, the most specific worker is taken.

Example: worker1: cloud=aws,gcp worker2: cloud=aws account=123

If the task is for cloud=aws and account=123, then only worker2 would get the task to execute not worker1.

Responses

Response samples

Content type
application/json
[
  • { }
]

List all outstanding work items

All work items that are initiated but not done are listed via this endpoint.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

certificate

Endpoints to access the certificate authority as well as signing functionality.

Retrieve the certificate authorities public certificate.

The certificate served here is only used to sign and validate.

Responses

Sign a certificate request.

Request Body schema: application/pkcs10

The certificate signing request (csr) in pkcs10 format.

string

Responses

system

Endpoints to get information about the system.

[WebSocket] Register as event listener and receive all events.

The client needs to send all the required headers for a ws connection and has to handle the websocket protocol.
Note this can not be tested from within swagger!

query Parameters
show
string

All events to show as a comma separated list

Responses

This endpoint signals if the system is ready to serve traffic.

Responses

Send a ping to the system and expect a pong.

Responses

debug

Endpoints to debug the system.

Transform the search into the raw database search

Experimental: This API is not stable and might be subject of change.
Show the underlying raw search.

path Parameters
graph_id
required
string
Example: resoto

The identifier of the graph

query Parameters
section
string
Enum: "reported" "desired" "metadata"

The name of the section used for all property paths. If not defined root is assumed.

Request Body schema: text/plain

The search to perform

string

Responses

Response samples

Content type
application/json
{
  • "query": "string",
  • "bind_vars": { }
}