# Relais

## 📫 Relais

## Create a Relay Session

> Create a relay session with users.

```json
{"openapi":"3.0.1","info":{"title":"Edgegap v1 API","version":"2026.04.24"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"https://api.edgegap.com"}],"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.04.24"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"https://api.edgegap.com"}],"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.04.24"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"https://api.edgegap.com"}],"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.04.24"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"https://api.edgegap.com"}],"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.04.24"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"https://api.edgegap.com"}],"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.04.24"},"tags":[{"name":"Relays"}],"servers":[{"url":"https://api.edgegap.com","description":"https://api.edgegap.com"}],"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":{}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edgegap.com/docs.edgegap.com-fr/docs/api/relais.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.