2015-01-18 00:28:53 +00:00
---
layout: "docs"
page_title: "Sessions (HTTP)"
sidebar_current: "docs-agent-http-sessions"
description: >
2015-02-12 19:50:54 +00:00
The Session endpoints are used to create, destroy, and query sessions.
2015-01-18 00:28:53 +00:00
---
# Session HTTP Endpoint
2015-02-12 19:50:54 +00:00
The Session endpoints are used to create, destroy, and query sessions.
2015-01-18 00:28:53 +00:00
The following endpoints are supported:
* [`/v1/session/create` ](#session_create ): Creates a new session
* [`/v1/session/destroy/<session>` ](#session_destroy ): Destroys a given session
* [`/v1/session/info/<session>` ](#session_info ): Queries a given session
* [`/v1/session/node/<node>` ](#session_node ): Lists sessions belonging to a node
2015-02-12 19:50:54 +00:00
* [`/v1/session/list` ](#session_list ): Lists all active sessions
* [`/v1/session/renew` ](#session_renew ): Renews a TTL-based session
2015-01-18 00:28:53 +00:00
2015-02-12 19:50:54 +00:00
All of the read session endpoints support blocking queries and all consistency modes.
2015-01-18 00:28:53 +00:00
### <a name="session_create"></a> /v1/session/create
The create endpoint is used to initialize a new session.
There is more documentation on sessions [here ](/docs/internals/sessions.html ).
2015-02-12 19:50:54 +00:00
Sessions must be associated with a node and may be associated with any number of checks.
2015-01-18 00:28:53 +00:00
2016-11-25 17:34:07 +00:00
The create endpoint expects a JSON request body to be `PUT` . The request
2015-01-18 00:28:53 +00:00
body must look like:
```javascript
{
"LockDelay": "15s",
"Name": "my-service-lock",
"Node": "foobar",
"Checks": ["a", "b", "c"],
"Behavior": "release",
"TTL": "0s"
}
```
None of the fields are mandatory, and in fact no body needs to be PUT
2015-02-12 19:50:54 +00:00
if the defaults are to be used.
By default, the agent's local datacenter is used; another datacenter
2016-11-25 17:34:07 +00:00
can be specified using the `?dc=` query parameter. However, it is not recommended
2015-02-12 19:50:54 +00:00
to use cross-datacenter sessions.
2016-11-25 17:34:07 +00:00
`LockDelay` can be specified as a duration string using an `s` suffix for
2015-02-13 01:34:40 +00:00
seconds. The default is 15s.
2015-02-12 19:50:54 +00:00
`Node` must refer to a node that is already registered, if specified. By default,
the agent's own node name is used.
`Name` can be used to provide a human-readable name for the Session.
`Checks` is used to provide a list of associated health checks. It is highly recommended
2016-11-25 16:00:02 +00:00
that, if you override this list, you include the default `serfHealth` .
2015-02-12 19:50:54 +00:00
`Behavior` can be set to either `release` or `delete` . This controls
2016-11-25 16:00:02 +00:00
the behavior when a session is invalidated. By default, this is `release` ,
2015-02-12 19:50:54 +00:00
causing any locks that are held to be released. Changing this to `delete`
2015-02-12 20:15:53 +00:00
causes any locks that are held to be deleted. `delete` is useful for creating ephemeral
2015-01-18 00:28:53 +00:00
key/value entries.
2016-11-25 17:34:07 +00:00
The `TTL` field is a duration string, and like `LockDelay` it can use `s` as
2015-11-14 23:30:53 +00:00
a suffix for seconds. If specified, it must be between 10s and 86400s currently.
2015-01-18 00:28:53 +00:00
When provided, the session is invalidated if it is not renewed before the TTL
2015-11-14 23:30:53 +00:00
expires. The lowest practical TTL should be used to keep the number of managed
sessions low. When locks are forcibly expired, such as during a leader election,
sessions may not be reaped for up to double this TTL, so long TTL values (>1 hour)
should be avoided. See the [session internals page ](/docs/internals/sessions.html )
for more documentation of this feature.
2015-01-18 00:28:53 +00:00
2015-02-12 19:50:54 +00:00
The return code is 200 on success and returns the ID of the created session:
2015-01-18 00:28:53 +00:00
```javascript
{
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}
```
### <a name="session_destroy"></a> /v1/session/destroy/\<session\>
2016-11-25 17:34:07 +00:00
The destroy endpoint is hit with a `PUT` and destroys the given session.
2016-11-25 16:00:02 +00:00
By default, the local datacenter is used, but the `?dc=` query parameter
2015-02-12 19:50:54 +00:00
can be used to specify the datacenter.
The session being destroyed must be provided on the path.
2015-01-18 00:28:53 +00:00
The return code is 200 on success.
### <a name="session_info"></a> /v1/session/info/\<session\>
2016-11-25 17:34:07 +00:00
This endpoint is hit with a `GET` and returns the requested session information
2015-02-12 19:50:54 +00:00
within a given datacenter. By default, the datacenter of the agent is queried;
2016-11-25 16:00:02 +00:00
however, the dc can be provided using the `?dc=` query parameter.
2015-02-12 19:50:54 +00:00
The session being queried must be provided on the path.
2015-01-18 00:28:53 +00:00
It returns a JSON body like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
}
]
```
If the session is not found, null is returned instead of a JSON list.
This endpoint supports blocking queries and all consistency modes.
### <a name="session_node"></a> /v1/session/node/\<node\>
2016-11-25 17:34:07 +00:00
This endpoint is hit with a `GET` and returns the active sessions
2015-02-12 19:50:54 +00:00
for a given node and datacenter. By default, the datacenter of the agent is queried;
2016-11-25 16:00:02 +00:00
however, the dc can be provided using the `?dc=` query parameter.
2015-02-12 19:50:54 +00:00
The node being queried must be provided on the path.
2015-01-18 00:28:53 +00:00
It returns a JSON body like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
},
...
]
```
This endpoint supports blocking queries and all consistency modes.
### <a name="session_list"></a> /v1/session/list
2016-11-25 17:34:07 +00:00
This endpoint is hit with a `GET` and returns the active sessions
2015-02-12 19:50:54 +00:00
for a given datacenter. By default, the datacenter of the agent is queried;
2016-11-25 16:00:02 +00:00
however, the dc can be provided using the `?dc=` query parameter.
2015-01-18 00:28:53 +00:00
It returns a JSON body like this:
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
},
...
]
```
This endpoint supports blocking queries and all consistency modes.
### <a name="session_renew"></a> /v1/session/renew/\<session\>
2016-11-25 17:34:07 +00:00
The renew endpoint is hit with a `PUT` and renews the given session.
2015-02-12 19:50:54 +00:00
This is used with sessions that have a TTL, and it extends the
2016-11-25 16:00:02 +00:00
expiration by the TTL. By default, the local datacenter is used, but the `?dc=`
2015-02-12 19:50:54 +00:00
query parameter can be used to specify the datacenter.
The session being renewed must be provided on the path.
2015-01-18 00:28:53 +00:00
2016-11-25 18:25:09 +00:00
The return code is 200 on success. The response JSON body looks like this:
2015-01-18 00:28:53 +00:00
```javascript
[
{
"LockDelay": 1.5e+10,
"Checks": [
"serfHealth"
],
"Node": "foobar",
"ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
"CreateIndex": 1086449
"Behavior": "release",
"TTL": "15s"
}
]
```
The response body includes the current session.
2015-02-12 19:50:54 +00:00
2016-11-25 16:00:02 +00:00
-> **Note:** Consul MAY return a TTL value higher than the one specified during session creation. This indicates the server is under high load and is requesting clients renew less often.