Skip to main content
POST
/
sessions
Exec
curl --request POST \
  --url https://use.hoop.dev/api/sessions \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "client_args": [
    "--verbose"
  ],
  "connection": "bash",
  "correlation_id": "task-12345",
  "labels": {},
  "metadata": {},
  "script": "echo 'hello from hoop'"
}
EOF
import requests

url = "https://use.hoop.dev/api/sessions"

payload = {
"client_args": ["--verbose"],
"connection": "bash",
"correlation_id": "task-12345",
"labels": {},
"metadata": {},
"script": "echo 'hello from hoop'"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
client_args: ['--verbose'],
connection: 'bash',
correlation_id: 'task-12345',
labels: {},
metadata: {},
script: 'echo \'hello from hoop\''
})
};

fetch('https://use.hoop.dev/api/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://use.hoop.dev/api/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'client_args' => [
'--verbose'
],
'connection' => 'bash',
'correlation_id' => 'task-12345',
'labels' => [

],
'metadata' => [

],
'script' => 'echo \'hello from hoop\''
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://use.hoop.dev/api/sessions"

payload := strings.NewReader("{\n \"client_args\": [\n \"--verbose\"\n ],\n \"connection\": \"bash\",\n \"correlation_id\": \"task-12345\",\n \"labels\": {},\n \"metadata\": {},\n \"script\": \"echo 'hello from hoop'\"\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://use.hoop.dev/api/sessions")
.header("Content-Type", "application/json")
.body("{\n \"client_args\": [\n \"--verbose\"\n ],\n \"connection\": \"bash\",\n \"correlation_id\": \"task-12345\",\n \"labels\": {},\n \"metadata\": {},\n \"script\": \"echo 'hello from hoop'\"\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://use.hoop.dev/api/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"client_args\": [\n \"--verbose\"\n ],\n \"connection\": \"bash\",\n \"correlation_id\": \"task-12345\",\n \"labels\": {},\n \"metadata\": {},\n \"script\": \"echo 'hello from hoop'\"\n}"

response = http.request(request)
puts response.read_body
{
  "execution_time": 5903,
  "exit_code": 1,
  "has_review": false,
  "output": "<string>",
  "output_status": "failed",
  "session_id": "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
  "truncated": false
}
{
"execution_time": 5903,
"exit_code": 1,
"has_review": false,
"output": "<string>",
"output_status": "failed",
"session_id": "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
"truncated": false
}
{
"message": "the error description"
}
{
"message": "the error description"
}
{
"message": "the error description"
}

Body

application/json

The request body resource

client_args
string[]

Additional arguments that will be joined when construction the command to be executed

Example:
["--verbose"]
connection
string

The target connection

Example:

"bash"

correlation_id
string

External workflow/task identifier that groups sessions belonging to the same logical run

Example:

"task-12345"

labels
object

DEPRECATED in flavor of metadata

metadata
object

Metadata contains attributes that is going to be available in the Session resource

script
string

The input of the execution

Example:

"echo 'hello from hoop'"

Response

The execution has finished

execution_time
integer

The amount of time the execution took in miliseconds

Example:

5903

exit_code
integer

The shell exit code, any non zero code means an error

  • 0 - Linux success exit code
  • -2 - internal gateway code that means it was unable to obtain a valid exit code number from the agent outcome packet
  • 254 - internal agent code that means it was unable to obtain a valid exit code number from the process
Example:

1

has_review
boolean

Inform if the connection has review enabled

Example:

false

output
string

Output contains an utf-8 output containing the outcome of the ad-hoc execution

output_status
enum<string>

Status reports if the outcome of the execution

  • success - The execution was executed with success
  • failed - In case of internal error or when the agent returns an exit code greater than 0 or different than -2
  • running - The execution may still be running.
Available options:
success,
failed,
running
Example:

"failed"

session_id
string<uuid>

Each execution creates a unique session id

Example:

"5701046A-7B7A-4A78-ABB0-A24C95E6FE54"

truncated
boolean

If the `output`` field is truncated or not

Example:

false