> For the complete documentation index, see [llms.txt](https://docs.edgegap.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.edgegap.com/docs.edgegap.com-fr/docs/api/relais.md).

# Relais

## 📫 Relais

## Create a Relay Session

> Create a relay session with users.

```json
{"openapi":"3.0.1","info":{"title":"Edgegap v1 API","version":"2026.06.17"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"[Manage API tokens in dashboard.](https://app.edgegap.com/user-settings?tab=tokens)"}},"schemas":{"RelaySession":{"required":["linked","ready","session_id","status"],"properties":{"session_id":{"type":"string","description":"The session ID"},"authorization_token":{"type":"integer","description":"The authorization token for the session"},"status":{"type":"string","description":"The status of the session"},"ready":{"type":"boolean","description":"If the session is ready to be used"},"linked":{"type":"boolean","description":"If the session is linked to a relay"},"error":{"type":"string","description":"The error message if the session failed"},"session_users":{"type":"array","description":"List Session Users","items":{"type":"object","properties":{"ip_address":{"type":"string","description":"The IP Address of the user"},"latitude":{"type":"number","description":"The latitude of the user"},"longitude":{"type":"number","description":"The longitude of the user"},"authorization_token":{"type":"integer","description":"The authorization token of the user"}}}},"relay":{"description":"The relay details the session is linked to","allOf":[{"type":"object","properties":{"ip":{"type":"string","description":"The IP Address of the relay"},"host":{"type":"string","description":"The host of the relay"},"ports":{"type":"object","properties":{"server":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}},"client":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}}}}}}]},"webhook_url":{"type":"string","description":"The webhook URL that we will call once the session is ready"}},"type":"object"},"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"A message depending of the request termination"}},"type":"object"}}},"paths":{"/v1/relays/sessions":{"post":{"summary":"Create a Relay Session","deprecated":false,"description":"Create a relay session with users.","operationId":"relay-session-create","tags":["Relays"],"parameters":[{"name":"Accept","in":"header","description":"","schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","description":"List of IP Addresses of session users","minItems":1,"items":{}},"filters":{"type":"array","description":"List of location filters to apply to the session","items":{}},"webhook_url":{"type":"string","description":"URL to send the session data to"}},"required":["users"]}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelaySession"}}},"headers":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}}}}}}}
```

## Get a Relay Session

> Retrieve the information for a relay session.

```json
{"openapi":"3.0.1","info":{"title":"Edgegap v1 API","version":"2026.06.17"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"[Manage API tokens in dashboard.](https://app.edgegap.com/user-settings?tab=tokens)"}},"schemas":{"RelaySession":{"required":["linked","ready","session_id","status"],"properties":{"session_id":{"type":"string","description":"The session ID"},"authorization_token":{"type":"integer","description":"The authorization token for the session"},"status":{"type":"string","description":"The status of the session"},"ready":{"type":"boolean","description":"If the session is ready to be used"},"linked":{"type":"boolean","description":"If the session is linked to a relay"},"error":{"type":"string","description":"The error message if the session failed"},"session_users":{"type":"array","description":"List Session Users","items":{"type":"object","properties":{"ip_address":{"type":"string","description":"The IP Address of the user"},"latitude":{"type":"number","description":"The latitude of the user"},"longitude":{"type":"number","description":"The longitude of the user"},"authorization_token":{"type":"integer","description":"The authorization token of the user"}}}},"relay":{"description":"The relay details the session is linked to","allOf":[{"type":"object","properties":{"ip":{"type":"string","description":"The IP Address of the relay"},"host":{"type":"string","description":"The host of the relay"},"ports":{"type":"object","properties":{"server":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}},"client":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}}}}}}]},"webhook_url":{"type":"string","description":"The webhook URL that we will call once the session is ready"}},"type":"object"},"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"A message depending of the request termination"}},"type":"object"}}},"paths":{"/v1/relays/sessions/{session_id}":{"get":{"summary":"Get a Relay Session","deprecated":false,"description":"Retrieve the information for a relay session.","operationId":"relay-session-get","tags":["Relays"],"parameters":[{"name":"session_id","in":"path","description":"","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"","schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelaySession"}}},"headers":{}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}}}}}}}
```

## List all Relay Sessions

> List all the active relay sessions.

```json
{"openapi":"3.0.1","info":{"title":"Edgegap v1 API","version":"2026.06.17"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"[Manage API tokens in dashboard.](https://app.edgegap.com/user-settings?tab=tokens)"}},"schemas":{"RelaySession":{"required":["linked","ready","session_id","status"],"properties":{"session_id":{"type":"string","description":"The session ID"},"authorization_token":{"type":"integer","description":"The authorization token for the session"},"status":{"type":"string","description":"The status of the session"},"ready":{"type":"boolean","description":"If the session is ready to be used"},"linked":{"type":"boolean","description":"If the session is linked to a relay"},"error":{"type":"string","description":"The error message if the session failed"},"session_users":{"type":"array","description":"List Session Users","items":{"type":"object","properties":{"ip_address":{"type":"string","description":"The IP Address of the user"},"latitude":{"type":"number","description":"The latitude of the user"},"longitude":{"type":"number","description":"The longitude of the user"},"authorization_token":{"type":"integer","description":"The authorization token of the user"}}}},"relay":{"description":"The relay details the session is linked to","allOf":[{"type":"object","properties":{"ip":{"type":"string","description":"The IP Address of the relay"},"host":{"type":"string","description":"The host of the relay"},"ports":{"type":"object","properties":{"server":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}},"client":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}}}}}}]},"webhook_url":{"type":"string","description":"The webhook URL that we will call once the session is ready"}},"type":"object"},"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"A message depending of the request termination"}},"type":"object"}}},"paths":{"/v1/relays/sessions":{"get":{"summary":"List all Relay Sessions","deprecated":false,"description":"List all the active relay sessions.","operationId":"relay-session-list","tags":["Relays"],"parameters":[{"name":"Accept","in":"header","description":"","schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"sessions":{"type":"array","description":"List of relay sessions","items":{"$ref":"#/components/schemas/RelaySession"}},"total_count":{"type":"integer","minimum":0},"pagination":{"type":"object","properties":{"number":{"type":"integer","minimum":0},"next_page_number":{"type":"integer","minimum":1,"nullable":true},"previous_page_number":{"type":"integer","minimum":1,"nullable":true},"paginator":{"type":"object","properties":{"num_pages":{"type":"integer","minimum":1}},"required":["num_pages"]},"has_next":{"type":"boolean","default":true},"has_previous":{"type":"boolean","default":false}},"required":["number","next_page_number","previous_page_number","paginator","has_next","has_previous"]}},"required":["total_count","pagination"]}}},"headers":{}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}}}}}}}
```

## Authorize a user on a Relay Session

> Authorize a user on a Relay Session

```json
{"openapi":"3.0.1","info":{"title":"Edgegap v1 API","version":"2026.06.17"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"[Manage API tokens in dashboard.](https://app.edgegap.com/user-settings?tab=tokens)"}},"schemas":{"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"A message depending of the request termination"}},"type":"object"}}},"paths":{"/v1/relays/sessions:authorize-user":{"post":{"summary":"Authorize a user on a Relay Session","deprecated":false,"description":"Authorize a user on a Relay Session","operationId":"relay-user-authorize","tags":["Relays"],"parameters":[{"name":"Accept","in":"header","description":"","schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","description":"Session Request ID (ex: 0724828881e2-S)"},"user_ip":{"type":"string","description":"User Ip to Authorize"}},"required":["session_id","user_ip"]}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","description":"The session ID"},"authorization_token":{"type":"integer","description":"The authorization token for the session"},"status":{"type":"string","description":"The status of the session"},"ready":{"type":"boolean","description":"If the session is ready to be used"},"linked":{"type":"boolean","description":"If the session is linked to a relay"},"error":{"type":"string","description":"The error message if the session failed"},"session_user":{"description":"List Session Users","allOf":[{}]},"relay":{"description":"The relay details the session is linked to","allOf":[{}]},"webhook_url":{"type":"string","description":"The webhook URL that we will call once the session is ready"}},"required":["linked","ready","session_id","status"]}}},"headers":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}}}}}}}
```

## Remove a user on a Relay Session

> Authorize a user on a Relay Session

```json
{"openapi":"3.0.1","info":{"title":"Edgegap v1 API","version":"2026.06.17"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"[Manage API tokens in dashboard.](https://app.edgegap.com/user-settings?tab=tokens)"}},"schemas":{"RelaySession":{"required":["linked","ready","session_id","status"],"properties":{"session_id":{"type":"string","description":"The session ID"},"authorization_token":{"type":"integer","description":"The authorization token for the session"},"status":{"type":"string","description":"The status of the session"},"ready":{"type":"boolean","description":"If the session is ready to be used"},"linked":{"type":"boolean","description":"If the session is linked to a relay"},"error":{"type":"string","description":"The error message if the session failed"},"session_users":{"type":"array","description":"List Session Users","items":{"type":"object","properties":{"ip_address":{"type":"string","description":"The IP Address of the user"},"latitude":{"type":"number","description":"The latitude of the user"},"longitude":{"type":"number","description":"The longitude of the user"},"authorization_token":{"type":"integer","description":"The authorization token of the user"}}}},"relay":{"description":"The relay details the session is linked to","allOf":[{"type":"object","properties":{"ip":{"type":"string","description":"The IP Address of the relay"},"host":{"type":"string","description":"The host of the relay"},"ports":{"type":"object","properties":{"server":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}},"client":{"type":"object","properties":{"port":{"type":"integer","description":"The port number"},"protocol":{"type":"string","description":"The protocol of the port"},"link":{"type":"string","description":"The link to the port"}}}}}}}]},"webhook_url":{"type":"string","description":"The webhook URL that we will call once the session is ready"}},"type":"object"},"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"A message depending of the request termination"}},"type":"object"}}},"paths":{"/v1/relays/sessions:revoke-user":{"post":{"summary":"Remove a user on a Relay Session","deprecated":false,"description":"Authorize a user on a Relay Session","operationId":"relay-user-revoke","tags":["Relays"],"parameters":[{"name":"Accept","in":"header","description":"","schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"session_id":{"type":"string","description":"Session Request ID (ex: 0724828881e2-S)"},"authorization_token":{"type":"integer","description":"Relay Authorization Token"}},"required":["authorization_token","session_id"]}}},"required":true},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelaySession"}}},"headers":{}},"204":{"description":"No Content","headers":{}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}}}}}}}
```

## Delete a Relay Session

> Delete a relay session.

```json
{"openapi":"3.0.1","info":{"title":"Edgegap v1 API","version":"2026.06.17"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"[Manage API tokens in dashboard.](https://app.edgegap.com/user-settings?tab=tokens)"}},"schemas":{"Error":{"required":["message"],"properties":{"message":{"type":"string","description":"A message depending of the request termination"}},"type":"object"}}},"paths":{"/v1/relays/sessions/{session_id}":{"delete":{"summary":"Delete a Relay Session","deprecated":false,"description":"Delete a relay session.","operationId":"relay-session-delete","tags":["Relays"],"parameters":[{"name":"session_id","in":"path","description":"","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","description":"","schema":{"type":"string"}},{"name":"Content-Type","in":"header","description":"","schema":{"type":"string"}}],"responses":{"204":{"description":"No Content","headers":{}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{}}}}}}}
```