github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/api-docs/allocations.mdx (about)

     1  ---
     2  layout: api
     3  page_title: Allocations - HTTP API
     4  sidebar_title: Allocations
     5  description: The /allocation endpoints are used to query for and interact with allocations.
     6  ---
     7  
     8  # Allocations HTTP API
     9  
    10  The `/allocation` endpoints are used to query for and interact with allocations.
    11  
    12  ## List Allocations
    13  
    14  This endpoint lists all allocations.
    15  
    16  | Method | Path              | Produces           |
    17  | ------ | ----------------- | ------------------ |
    18  | `GET`  | `/v1/allocations` | `application/json` |
    19  
    20  The table below shows this endpoint's support for
    21  [blocking queries](/api-docs#blocking-queries) and
    22  [required ACLs](/api-docs#acls).
    23  
    24  | Blocking Queries | ACL Required         |
    25  | ---------------- | -------------------- |
    26  | `YES`            | `namespace:read-job` |
    27  
    28  ### Parameters
    29  
    30  - `prefix` `(string: "")`- Specifies a string to filter allocations based on an
    31    ID prefix. Because the value is decoded to bytes, the prefix must have an
    32    even number of hexadecimal characters (0-9a-f). This is specified as a query
    33    string parameter.
    34  
    35  - `namespace` `(string: "default")` - Specifies the namespace to search. Specifying
    36    `*` would return all allocations across all the authorized namespaces.
    37  
    38  - `resources` `(bool: false)` - Specifies whether or not to include the
    39    `AllocatedResources` field in the response.
    40  
    41  - `task_states` `(bool: true)` - Specifies whether or not to include the
    42    `TaskStates` field in the response. TaskStates are included by default but
    43    can represent a large percentage of the overall response size. Clusters with
    44    a large number of allocations may set `task_states=false` to significantly
    45    reduce the size of the response.
    46  
    47  ### Sample Request
    48  
    49  ```shell-session
    50  $ curl \
    51      https://localhost:4646/v1/allocations
    52  ```
    53  
    54  ```shell-session
    55  $ curl \
    56      https://localhost:4646/v1/allocations?prefix=a8198d79
    57  ```
    58  
    59  ```shell-session
    60  $ curl \
    61      https://localhost:4646/v1/allocations?namespace=*&prefix=a8198d79
    62  ```
    63  
    64  ### Sample Response
    65  
    66  ```json
    67  [
    68    {
    69      "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
    70      "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
    71      "Name": "example.cache[0]",
    72      "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
    73      "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
    74      "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
    75      "RescheduleTracker": {
    76        "Events": [
    77          {
    78            "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
    79            "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
    80            "RescheduleTime": 1517434161192946200,
    81            "Delay": "5000000000"
    82          }
    83        ]
    84      },
    85      "JobID": "example",
    86      "TaskGroup": "cache",
    87      "DesiredStatus": "run",
    88      "DesiredDescription": "",
    89      "ClientStatus": "running",
    90      "ClientDescription": "",
    91      "TaskStates": {
    92        "redis": {
    93          "State": "running",
    94          "FinishedAt": "0001-01-01T00:00:00Z",
    95          "LastRestart": "0001-01-01T00:00:00Z",
    96          "Restarts": 0,
    97          "StartedAt": "2017-07-25T23:36:26.106431265Z",
    98          "Failed": false,
    99          "Events": [
   100            {
   101              "Type": "Received",
   102              "Time": 1495747371795703800,
   103              "FailsTask": false,
   104              "RestartReason": "",
   105              "SetupError": "",
   106              "DriverError": "",
   107              "ExitCode": 0,
   108              "Signal": 0,
   109              "Message": "",
   110              "KillTimeout": 0,
   111              "KillError": "",
   112              "KillReason": "",
   113              "StartDelay": 0,
   114              "DownloadError": "",
   115              "ValidationError": "",
   116              "DiskLimit": 0,
   117              "FailedSibling": "",
   118              "VaultError": "",
   119              "TaskSignalReason": "",
   120              "TaskSignal": "",
   121              "DriverMessage": ""
   122            },
   123            {
   124              "Type": "Driver",
   125              "Time": 1495747371798867200,
   126              "FailsTask": false,
   127              "RestartReason": "",
   128              "SetupError": "",
   129              "DriverError": "",
   130              "ExitCode": 0,
   131              "Signal": 0,
   132              "Message": "",
   133              "KillTimeout": 0,
   134              "KillError": "",
   135              "KillReason": "",
   136              "StartDelay": 0,
   137              "DownloadError": "",
   138              "ValidationError": "",
   139              "DiskLimit": 0,
   140              "FailedSibling": "",
   141              "VaultError": "",
   142              "TaskSignalReason": "",
   143              "TaskSignal": "",
   144              "DriverMessage": "Downloading image redis:3.2"
   145            },
   146            {
   147              "Type": "Started",
   148              "Time": 1495747379525667800,
   149              "FailsTask": false,
   150              "RestartReason": "",
   151              "SetupError": "",
   152              "DriverError": "",
   153              "ExitCode": 0,
   154              "Signal": 0,
   155              "Message": "",
   156              "KillTimeout": 0,
   157              "KillError": "",
   158              "KillReason": "",
   159              "StartDelay": 0,
   160              "DownloadError": "",
   161              "ValidationError": "",
   162              "DiskLimit": 0,
   163              "FailedSibling": "",
   164              "VaultError": "",
   165              "TaskSignalReason": "",
   166              "TaskSignal": "",
   167              "DriverMessage": ""
   168            }
   169          ]
   170        }
   171      },
   172      "CreateIndex": 54,
   173      "ModifyIndex": 57,
   174      "CreateTime": 1495747371794276400,
   175      "ModifyTime": 1495747371794276400
   176    }
   177  ]
   178  ```
   179  
   180  ## Read Allocation
   181  
   182  This endpoint reads information about a specific allocation.
   183  
   184  | Method | Path                       | Produces           |
   185  | ------ | -------------------------- | ------------------ |
   186  | `GET`  | `/v1/allocation/:alloc_id` | `application/json` |
   187  
   188  The table below shows this endpoint's support for
   189  [blocking queries](/api-docs#blocking-queries) and
   190  [required ACLs](/api-docs#acls).
   191  
   192  | Blocking Queries | ACL Required         |
   193  | ---------------- | -------------------- |
   194  | `YES`            | `namespace:read-job` |
   195  
   196  ### Parameters
   197  
   198  - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
   199    must be the full UUID, not the short 8-character one. This is specified as
   200    part of the path.
   201  
   202  ### Sample Request
   203  
   204  ```shell-session
   205  $ curl \
   206      https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577
   207  ```
   208  
   209  ### Sample Response
   210  
   211  ```json
   212  {
   213    "ID": "a8198d79-cfdb-6593-a999-1e9adabcba2e",
   214    "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
   215    "Name": "example.cache[0]",
   216    "NodeID": "fb2170a8-257d-3c64-b14d-bc06cc94e34c",
   217    "PreviousAllocation": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
   218    "NextAllocation": "cd13d9b9-4f97-7184-c88b-7b451981616b",
   219    "RescheduleTracker": {
   220      "Events": [
   221        {
   222          "PrevAllocID": "516d2753-0513-cfc7-57ac-2d6fac18b9dc",
   223          "PrevNodeID": "9230cd3b-3bda-9a3f-82f9-b2ea8dedb20e",
   224          "RescheduleTime": 1517434161192946200,
   225          "Delay": "5000000000"
   226        }
   227      ]
   228    },
   229    "JobID": "example",
   230    "Job": {
   231      "Region": "global",
   232      "ID": "example",
   233      "ParentID": "",
   234      "Name": "example",
   235      "Type": "service",
   236      "Priority": 50,
   237      "AllAtOnce": false,
   238      "Datacenters": ["dc1"],
   239      "Constraints": null,
   240      "Affinities": null,
   241      "TaskGroups": [
   242        {
   243          "Name": "cache",
   244          "Count": 1,
   245          "Constraints": null,
   246          "Affinities": null,
   247          "RestartPolicy": {
   248            "Attempts": 10,
   249            "Interval": 300000000000,
   250            "Delay": 25000000000,
   251            "Mode": "delay"
   252          },
   253          "Spreads": null,
   254          "Tasks": [
   255            {
   256              "Name": "redis",
   257              "Driver": "docker",
   258              "User": "",
   259              "Config": {
   260                "port_map": [
   261                  {
   262                    "db": 6379
   263                  }
   264                ],
   265                "image": "redis:3.2"
   266              },
   267              "Env": null,
   268              "Services": [
   269                {
   270                  "Name": "redis-cache",
   271                  "PortLabel": "db",
   272                  "Tags": ["global", "cache"],
   273                  "Checks": [
   274                    {
   275                      "Name": "alive",
   276                      "Type": "tcp",
   277                      "Command": "",
   278                      "Args": null,
   279                      "Path": "",
   280                      "Protocol": "",
   281                      "PortLabel": "",
   282                      "Interval": 10000000000,
   283                      "Timeout": 2000000000,
   284                      "InitialStatus": ""
   285                    }
   286                  ]
   287                }
   288              ],
   289              "Vault": null,
   290              "Templates": null,
   291              "Constraints": null,
   292              "Affinities": null,
   293              "Resources": {
   294                "CPU": 500,
   295                "MemoryMB": 10,
   296                "DiskMB": 0,
   297                "Networks": [
   298                  {
   299                    "Device": "",
   300                    "CIDR": "",
   301                    "IP": "",
   302                    "MBits": 10,
   303                    "ReservedPorts": null,
   304                    "DynamicPorts": [
   305                      {
   306                        "Label": "db",
   307                        "Value": 0
   308                      }
   309                    ]
   310                  }
   311                ]
   312              },
   313              "Spreads": null,
   314              "DispatchPayload": null,
   315              "Meta": null,
   316              "KillTimeout": 5000000000,
   317              "LogConfig": {
   318                "MaxFiles": 10,
   319                "MaxFileSizeMB": 10
   320              },
   321              "Artifacts": null,
   322              "Leader": false
   323            }
   324          ],
   325          "EphemeralDisk": {
   326            "Sticky": false,
   327            "SizeMB": 300,
   328            "Migrate": false
   329          },
   330          "Meta": null
   331        }
   332      ],
   333      "Update": {
   334        "Stagger": 10000000000,
   335        "MaxParallel": 0
   336      },
   337      "Periodic": null,
   338      "ParameterizedJob": null,
   339      "Payload": null,
   340      "Spreads": null,
   341      "Meta": null,
   342      "VaultToken": "",
   343      "Status": "pending",
   344      "StatusDescription": "",
   345      "CreateIndex": 52,
   346      "ModifyIndex": 52,
   347      "JobModifyIndex": 52
   348    },
   349    "TaskGroup": "cache",
   350    "Resources": {
   351      "CPU": 500,
   352      "MemoryMB": 10,
   353      "DiskMB": 300,
   354      "Networks": [
   355        {
   356          "Device": "lo0",
   357          "CIDR": "",
   358          "IP": "127.0.0.1",
   359          "MBits": 10,
   360          "ReservedPorts": null,
   361          "DynamicPorts": [
   362            {
   363              "Label": "db",
   364              "Value": 23116
   365            }
   366          ]
   367        }
   368      ]
   369    },
   370    "SharedResources": {
   371      "CPU": 0,
   372      "MemoryMB": 0,
   373      "DiskMB": 300,
   374      "Networks": null
   375    },
   376    "TaskResources": {
   377      "redis": {
   378        "CPU": 500,
   379        "MemoryMB": 10,
   380        "DiskMB": 0,
   381        "Networks": [
   382          {
   383            "Device": "lo0",
   384            "CIDR": "",
   385            "IP": "127.0.0.1",
   386            "MBits": 10,
   387            "ReservedPorts": null,
   388            "DynamicPorts": [
   389              {
   390                "Label": "db",
   391                "Value": 23116
   392              }
   393            ]
   394          }
   395        ]
   396      }
   397    },
   398    "Metrics": {
   399      "NodesEvaluated": 1,
   400      "NodesFiltered": 0,
   401      "NodesAvailable": {
   402        "dc1": 1
   403      },
   404      "ClassFiltered": null,
   405      "ConstraintFiltered": null,
   406      "NodesExhausted": 0,
   407      "ClassExhausted": null,
   408      "DimensionExhausted": null,
   409      "Scores": {
   410        "fb2170a8-257d-3c64-b14d-bc06cc94e34c.binpack": 0.6205732522109244
   411      },
   412      "AllocationTime": 31729,
   413      "CoalescedFailures": 0
   414    },
   415    "DesiredStatus": "run",
   416    "DesiredDescription": "",
   417    "ClientStatus": "running",
   418    "ClientDescription": "",
   419    "TaskStates": {
   420      "redis": {
   421        "State": "running",
   422        "Failed": false,
   423        "FinishedAt": "0001-01-01T00:00:00Z",
   424        "LastRestart": "0001-01-01T00:00:00Z",
   425        "Restarts": 0,
   426        "StartedAt": "2017-07-25T23:36:26.106431265Z",
   427        "Events": [
   428          {
   429            "Type": "Received",
   430            "Time": 1495747371795703800,
   431            "FailsTask": false,
   432            "RestartReason": "",
   433            "SetupError": "",
   434            "DriverError": "",
   435            "ExitCode": 0,
   436            "Signal": 0,
   437            "Message": "",
   438            "KillTimeout": 0,
   439            "KillError": "",
   440            "KillReason": "",
   441            "StartDelay": 0,
   442            "DownloadError": "",
   443            "ValidationError": "",
   444            "DiskLimit": 0,
   445            "FailedSibling": "",
   446            "VaultError": "",
   447            "TaskSignalReason": "",
   448            "TaskSignal": "",
   449            "DriverMessage": ""
   450          },
   451          {
   452            "Type": "Driver",
   453            "Time": 1495747371798867200,
   454            "FailsTask": false,
   455            "RestartReason": "",
   456            "SetupError": "",
   457            "DriverError": "",
   458            "ExitCode": 0,
   459            "Signal": 0,
   460            "Message": "",
   461            "KillTimeout": 0,
   462            "KillError": "",
   463            "KillReason": "",
   464            "StartDelay": 0,
   465            "DownloadError": "",
   466            "ValidationError": "",
   467            "DiskLimit": 0,
   468            "FailedSibling": "",
   469            "VaultError": "",
   470            "TaskSignalReason": "",
   471            "TaskSignal": "",
   472            "DriverMessage": "Downloading image redis:3.2"
   473          },
   474          {
   475            "Type": "Started",
   476            "Time": 1495747379525667800,
   477            "FailsTask": false,
   478            "RestartReason": "",
   479            "SetupError": "",
   480            "DriverError": "",
   481            "ExitCode": 0,
   482            "Signal": 0,
   483            "Message": "",
   484            "KillTimeout": 0,
   485            "KillError": "",
   486            "KillReason": "",
   487            "StartDelay": 0,
   488            "DownloadError": "",
   489            "ValidationError": "",
   490            "DiskLimit": 0,
   491            "FailedSibling": "",
   492            "VaultError": "",
   493            "TaskSignalReason": "",
   494            "TaskSignal": "",
   495            "DriverMessage": ""
   496          }
   497        ]
   498      }
   499    },
   500    "PreviousAllocation": "",
   501    "CreateIndex": 54,
   502    "ModifyIndex": 57,
   503    "AllocModifyIndex": 54,
   504    "CreateTime": 1495747371794276400,
   505    "ModifyTime": 1495747371794276400
   506  }
   507  ```
   508  
   509  #### Field Reference
   510  
   511  - `Job` - A copy of the job at the time that the allocation is created or
   512    updated. This is primarily intended for use by the Nomad client when running
   513    the allocation, and it may include stale information on some job fields.
   514    Up-to-date information about the job status is available from the
   515    [jobs API](/api-docs/jobs); take care to fetch the version of the job
   516    associated with this allocation.
   517  
   518  - `TaskStates` - A map of tasks to their current state and the latest events
   519    that have effected the state. `TaskState` objects contain the following
   520    fields:
   521  
   522    - `State`: The task's current state. It can have one of the following
   523      values:
   524  
   525      - `TaskStatePending` - The task is waiting to be run, either for the first
   526        time or due to a restart.
   527  
   528      - `TaskStateRunning` - The task is currently running.
   529  
   530      - `TaskStateDead` - The task is dead and will not run again.
   531  
   532    - `StartedAt`: The time the task was last started at. Can be updated through
   533      restarts.
   534  
   535    - `FinishedAt`: The time the task was finished at.
   536  
   537    - `LastRestart`: The last time the task was restarted.
   538  
   539    - `Restarts`: The number of times the task has restarted.
   540  
   541    - `Events` - An event contains metadata about the event. The latest 10 events
   542      are stored per task. Each event is timestamped (Unix nanoseconds) and has one
   543      of the following types:
   544  
   545      - `Setup Failure` - The task could not be started because there was a
   546        failure setting up the task prior to it running.
   547  
   548      - `Driver Failure` - The task could not be started due to a failure in the
   549        driver.
   550  
   551      - `Started` - The task was started; either for the first time or due to a
   552        restart.
   553  
   554      - `Terminated` - The task was started and exited.
   555  
   556      - `Killing` - The task has been sent the kill signal.
   557  
   558      - `Killed` - The task was killed by a user.
   559  
   560      - `Received` - The task has been pulled by the client at the given timestamp.
   561  
   562      - `Failed Validation` - The task was invalid and as such it didn't run.
   563  
   564      - `Restarting` - The task terminated and is being restarted.
   565  
   566      - `Not Restarting` - the task has failed and is not being restarted because
   567        it has exceeded its restart policy.
   568  
   569      - `Downloading Artifacts` - The task is downloading the artifact(s)
   570      - specified in the task.
   571  
   572      - `Failed Artifact Download` - Artifact(s) specified in the task failed to
   573        download.
   574  
   575      - `Restart Signaled` - The task was singled to be restarted.
   576  
   577      - `Signaling` - The task was is being sent a signal.
   578  
   579      - `Sibling Task Failed` - A task in the same task group failed.
   580  
   581      - `Leader Task Dead` - The group's leader task is dead.
   582  
   583      - `Driver` - A message from the driver.
   584  
   585      - `Task Setup` - Task setup messages.
   586  
   587      - `Building Task Directory` - Task is building its file system.
   588  
   589      Depending on the type the event will have applicable annotations.
   590  
   591  ## Stop Allocation
   592  
   593  This endpoint stops and reschedules a specific allocation.
   594  
   595  | Method         | Path                            | Produces           |
   596  | -------------- | ------------------------------- | ------------------ |
   597  | `POST` / `PUT` | `/v1/allocation/:alloc_id/stop` | `application/json` |
   598  
   599  The table below shows this endpoint's support for
   600  [blocking queries](/api-docs#blocking-queries) and
   601  [required ACLs](/api-docs#acls).
   602  
   603  | Blocking Queries | ACL Required                |
   604  | ---------------- | --------------------------- |
   605  | `NO`             | `namespace:alloc-lifecycle` |
   606  
   607  ### Parameters
   608  
   609  - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
   610    must be the full UUID, not the short 8-character one. This is specified as
   611    part of the path.
   612  
   613  ### Sample Request
   614  
   615  ```shell-session
   616  $ curl -X POST \
   617      https://localhost:4646/v1/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/stop
   618  ```
   619  
   620  ### Sample Response
   621  
   622  ```json
   623  {
   624    "EvalID": "5456bd7a-9fc0-c0dd-6131-cbee77f57577",
   625    "Index": 54
   626  }
   627  ```
   628  
   629  ## Signal Allocation
   630  
   631  This endpoint sends a signal to an allocation or task.
   632  
   633  | Method         | Path                                     | Produces           |
   634  | -------------- | ---------------------------------------- | ------------------ |
   635  | `POST` / `PUT` | `/v1/client/allocation/:alloc_id/signal` | `application/json` |
   636  
   637  The table below shows this endpoint's support for
   638  [blocking queries](/api-docs#blocking-queries) and
   639  [required ACLs](/api-docs#acls).
   640  
   641  | Blocking Queries | ACL Required                |
   642  | ---------------- | --------------------------- |
   643  | `NO`             | `namespace:alloc-lifecycle` |
   644  
   645  ### Parameters
   646  
   647  - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
   648    must be the full UUID, not the short 8-character one. This is specified as
   649    part of the path.
   650  
   651  ### Sample Payload
   652  
   653  ```json
   654  {
   655    "Signal": "SIGUSR1",
   656    "Task": "FOO"
   657  }
   658  ```
   659  
   660  ### Sample Request
   661  
   662  ```shell-session
   663  $ curl -X POST -d '{"Signal": "SIGUSR1" }' \
   664      https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/signal
   665  ```
   666  
   667  ### Sample Response
   668  
   669  ```json
   670  {}
   671  ```
   672  
   673  ## Restart Allocation
   674  
   675  This endpoint restarts an allocation or task in-place.
   676  
   677  | Method         | Path                                      | Produces           |
   678  | -------------- | ----------------------------------------- | ------------------ |
   679  | `POST` / `PUT` | `/v1/client/allocation/:alloc_id/restart` | `application/json` |
   680  
   681  The table below shows this endpoint's support for
   682  [blocking queries](/api-docs#blocking-queries) and
   683  [required ACLs](/api-docs#acls).
   684  
   685  | Blocking Queries | ACL Required                |
   686  | ---------------- | --------------------------- |
   687  | `NO`             | `namespace:alloc-lifecycle` |
   688  
   689  ### Parameters
   690  
   691  - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
   692    must be the full UUID, not the short 8-character one. This is specified as
   693    part of the path.
   694  
   695  ### Sample Payload
   696  
   697  ```json
   698  {
   699    "Task": "FOO"
   700  }
   701  ```
   702  
   703  ### Sample Request
   704  
   705  ```shell-session
   706  $ curl -X POST -d '{"Task": "redis" }' \
   707      https://localhost:4646/v1/client/allocation/5456bd7a-9fc0-c0dd-6131-cbee77f57577/restart
   708  ```
   709  
   710  ### Sample Response
   711  
   712  ```json
   713  {}
   714  ```
   715  
   716  ## Exec Allocation
   717  
   718  This endpoint executes a command inside the isolation container where an allocation is running.
   719  It opens a WebSocket to transmit input to and output from the command.
   720  
   721  | Method | Path                       | Produces                   |
   722  | ------ | -------------------------- | -------------------------- |
   723  | `WebSocket` | `/v1/client/allocation/:alloc_id/exec` | WebSocket JSON streams |
   724  
   725  The table below shows this endpoint's support for
   726  [blocking queries](/api/index.html#blocking-queries) and
   727  [required ACLs](/api/index.html#acls).
   728  
   729  | Blocking Queries | ACL Required         |
   730  | ---------------- | -------------------- |
   731  | `NO`            | `namespace:alloc-exec` (and `namespace:alloc-node-exec` if target task uses raw_exec driver) |
   732  
   733  ### Parameters
   734  
   735  - `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
   736    must be the full UUID, not the short 8-character one. This is specified as
   737    part of the path.
   738  - `command` `(string: <required>)` - Specifies the command to be executed.  This
   739    must be a JSON-encoded array of the command to be executed, e.g. `["echo", "hi"]`
   740    or `["/bin/bash"]`. This is specified as a query parameter.
   741  - `task` `(string: <required>)` - Specifies the task name, as a query parameter.
   742  - `tty` `(bool: false)` - Specifies whether a TTY is allocated for this task, as
   743    a query parameter.
   744  - `ws_handshake` `(bool: false)` - Specifies whether to expect the authentication
   745    token in the first frame, as a query parameter.
   746  
   747  ### Request Frames
   748  
   749  Request frames represent the `stdin` stream from the command as well as TTY resize events.
   750  When `?ws_handshake=true`, the first request frame must contain the authentication token.
   751  
   752  The following are valid formats:
   753  
   754  ```
   755  # sending authentication token
   756  {"version":1,"auth_token":"fc3c1968-8d31-5c50-9617-3db2e19ef32e"}
   757  
   758  # sending stdin data
   759  {"stdin": {"data": "...base64 encoded string of bytes ..."}}
   760  
   761  # indicating stdin is closed
   762  {"stdin": {"close": true}}
   763  
   764  # indicating that TTY was resized
   765  {"tty_size": {"height": <characters>, "width": <characters>}}
   766  
   767  # basic application-level heartbeat
   768  {}
   769  ```
   770  
   771  ### Response Frames
   772  
   773  Response frames represent `stdout` and `stderr` output from the command as well as exit codes:
   774  
   775  ```
   776  # transferring stdout data
   777  {"stdout": {"data": "...base64 encoded string of bytes ..."}}
   778  
   779  # signaling that host closed stdout
   780  {"stdout": {"close": true}}
   781  
   782  # transferring stderr data
   783  {"stderr": {"data": "...base64 encoded string of bytes ..."}}
   784  
   785  # signaling that host closed stderr
   786  {"stderr": {"close": true}}
   787  
   788  # signaling process exited
   789  {"exited": true, "result": {"exit_code": <exit_code_int>}}
   790  
   791  # basic application-level heartbeat
   792  {}
   793  ```
   794  
   795  ### Sample Request and Response
   796  
   797  Request and response frames encompass the full range of terminal emulator inputs and outputs, including the control characters necessary to render interactive applications. The example response includes instances of the ANSI “control sequence introducer” (CSI), which is ASCII code 27 followed by `[`.
   798  
   799  ```
   800  # \x12: form feed, to clear terminal
   801  {"stdin":{"data":"DA=="}}
   802  
   803  # "\x1b[H\x1b[2J$ ":
   804  # CSI-H (move cursor to top left corner), CSI-2J (clear entire screen), print "$ "
   805  {"stdout":{"data":"G1tIG1sySiQg"}}