---
title: "Create a Relay Session"
method: POST
path: "/v1/relays/sessions"
tags: ["Relays"]
---

# Create a Relay Session

`POST /v1/relays/sessions`

## Request

- Base URL: `https://api.edgegap.com`
- URL: `https://api.edgegap.com/v1/relays/sessions`
- Auth: API key in header `authorization`

Create a relay session with users.

## Request body

- RelaySessionCreatePayload
  - `users` RelaySessionUser[], required: List of IP Addresses of session users
    - `ip` string, required: IP Address of session user
  - `filters` RelayFilterModel[]: List of location filters to apply to the session
    - `field` string, required: The field to filter
    - `values` string[], required: The values to filter
    - `filter_type` 'any' | 'all' | 'not', required: The type of filter
  - `webhook_url` string: URL to send the session data to

## Response `200`

Success

- RelaySessionBaseResponse
  - `session_id` string, required: The session ID
  - `authorization_token` integer: The authorization token for the session
  - `status` string, required: The status of the session
  - `ready` boolean, required: If the session is ready to be used
  - `linked` boolean, required: If the session is linked to a relay
  - `error` string: The error message if the session failed
  - `session_users` RelaySessionUserResponse[]: List Session Users
    - `ip_address` string: The IP Address of the user
    - `latitude` number: The latitude of the user
    - `longitude` number: The longitude of the user
    - `authorization_token` integer: The authorization token of the user
  - `relay` RelayResponse
    - `ip` string: The IP Address of the relay
    - `host` string: The host of the relay
    - `ports` MappedPortResponse
      - `server` ServerRelayPort
        - `port` integer: The port number
        - `protocol` string: The protocol of the port
        - `link` string: The link to the port
      - `client` ClientRelayPort
        - `port` integer: The port number
        - `protocol` string: The protocol of the port
        - `link` string: The link to the port
  - `webhook_url` string: The webhook URL that we will call once the session is ready

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/edgegap/apis/edgegap-v1.md) · [All operations](https://skmtc.dev/edgegap/apis/edgegap-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/edgegap/apis/edgegap-v1/revisions/9fa2b393a6be?raw)