Permalink API

The Permalink API enables developers to pre-define meeting rooms, generate sharable guest links, and initiate meetings on demand.

Only registered hosts can start meetings, while guests must wait for a host to begin the session.

All meeting room settings remain configurable throughout the lifetime of the permalink.

info

API URL for all following endpoints: https://api.eyeson.team

Create permalink

POST /permalink
HEADERS Authorization
RESPONSES 201 Created, 400 Bad Request, 401 Unauthorized, 503 Service Unavailable

It is required to define the meeting host at least with user[name].

expires_at

Type: ISO8601 Timestamp (optional)
Optional Timestamp when permalink meetings can no longer be started. E.g. 2024-05-15T10:00:00.000Z

user[id]

Type: STRING (optional)
You can supply a custom user id to identify the user in further REST requests without the need of remembering the Eyeson user id e.g. your internal user id, an e-mail address, phone number, etc. If kept empty, a random id will be assigned.

user[name]

Type: STRING (required)
Display name of the user.

options[exit_url]

Type: URL (optional)
Exit destination, URL for exit button in Prebuilt-UI.

options[recording_available]

Type: BOOLEAN (optional)
Default: true
Allow recordings.

options[widescreen]

Type: BOOLEAN (optional)
Default: true
Run meeting in widescreen mode (16:9 aspect ratio).

options[custom_fields][locale]

Type: Language Code (optional)
User preferred language code (en, de, fr) in Prebuilt-UI.

warning

Room id is ignored!

Example response

{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": "9clgjJXl1NzbcmF5vfXWhAVJ",
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": {
        "id": "667a7cf6dfd92d8815fcfb31",
        "name": "John Doe",
        "avatar": null,
        "guest": false,
        "joined_at": "2024-05-14T13:34:19.468Z"
    },
    "options": {
        "show_names": true,
        "show_label": true,
        "exit_url": null,
        "recording_available": true,
        "broadcast_available": true,
        "layout_available": true,
        "layout": "auto",
        "reaction_available": true,
        "suggest_guest_names": true,
        "lock_available": false,
        "kick_available": true,
        "sfu_mode": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": "https://app.eyeson.team/permalink?9clgjJXl1NzbcmF5vfXWhAVJ",
        "guest_join": "https://app.eyeson.team/permalink?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

info

If you're using the GUI and Guest-join links, the "Start meeting from permalink" and "Register guest user" actions are handled automatically.

Get list of permalinks

GET /permalink
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized

page

Type: INTEGER (optional)
Fetch next set of permalinks

limit

Type: INTEGER (optional)
Default: 25

expired

Type: BOOLEAN (optional) omit for full list, true for only expired, false for only non-expired

Example response

{
    "page": 1,
    "limit": 25,
    "total": 3,
    "items": [
        {
            ... // see permalink object above
        },
        {
            ...
        },
        {
            ...
        }
    ]
}

Get specific permalink by Id

GET /permalink/<permalink_id>
HEADERS Authorization
RESPONSES 200 OK, 404 Not Found

warning

Please note that permalink.user_token, user, and links.gui are null, because the information is about the permalink and not the permalink user.

Example response

{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": null,
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": null,
    "options": {
        "show_names": true,
        "show_label": true,
        "exit_url": null,
        "recording_available": true,
        "broadcast_available": true,
        "layout_available": true,
        "layout": "auto",
        "reaction_available": true,
        "suggest_guest_names": true,
        "lock_available": false,
        "kick_available": true,
        "sfu_mode": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": null,
        "guest_join": "https://app.eyeson.team/permalink?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

Update permalink

PUT /permalink/<permalink_id>
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized, 404 Not Found

Returns the updated permalink object.

Note that also expires_at can be adjusted.

Delete permalink

DELETE /permalink/<permalink_id>
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized, 404 Not Found

Register host user to permalink

Host users are allowed to start the meeting. Guests need to wait until a meeting is up and running.

warning

Host user GUI links need to be kept secret! Make sure to only share guest links!

POST /permalink/<permalink_id>/users
HEADERS Authorization
RESPONSES 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found

Example response

{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": "QTb1BqRO3YcwV6XmzhoVI7Wt",
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": {
        "id": "667a7cf6dfd92d8815fcfb31",
        "name": "Jane",
        "avatar": null,
        "guest": false,
        "joined_at": "2024-05-15T13:32:19.468Z"
    },
    "options": {
        "show_names": true,
        "show_label": true,
        "exit_url": null,
        "recording_available": true,
        "broadcast_available": true,
        "layout_available": true,
        "layout": "auto",
        "reaction_available": true,
        "suggest_guest_names": true,
        "lock_available": false,
        "kick_available": true,
        "sfu_mode": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": "https://app.eyeson.team/permalink?QTb1BqRO3YcwV6XmzhoVI7Wt",
        "guest_join": "https://app.eyeson.team/permalink?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

Remove host user from permalink

In case you need to revoke a user-token or prevent a user from starting a meeting, the user-token can be simply deleted.

DELETE /permalink/<permalink_id>/users/<user-token>
HEADERS Authorization
RESPONSES 200 OK, 401 Unauthorized, 404 Not Found

Meeting information

Receive information about the room instance without authentication header.

Note the room.started_at parameter. It is null if no meeting is running, otherwise it contains the start date in ISO8601 Timestamp format, e.g. 2024-05-14T13:34:19.468Z.

GET /permalink/<user_token | guest_token>
RESPONSES 200 OK, 404 Not Found

Example response

{
    "permalink": {
        "id": "6643685b858f54f55edef723",
        "created_at": "2024-05-14T13:34:19.468Z",
        "user_token": null,
        "guest_token": "R2SdUxiqKhpBoUu0oi0pZZkZ",
        "expires_at": null
    },
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "started_at": null
    },
    "team": {
        "name": "Test"
    },
    "user": null,
    "options": {
        "show_names": true,
        "show_label": true,
        "exit_url": null,
        "recording_available": true,
        "broadcast_available": true,
        "layout_available": true,
        "layout": "auto",
        "reaction_available": true,
        "suggest_guest_names": true,
        "lock_available": false,
        "kick_available": true,
        "sfu_mode": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "links": {
        "self": "https://api.eyeson.team/permalink/6643685b858f54f55edef723",
        "gui": null,
        "guest_join": "https://app.eyeson.team/permalinks?guest=R2SdUxiqKhpBoUu0oi0pZZkZ"
    }
}

Start meeting from permalink

Create a new meeting or join an existing via the permalink's user_token.

POST /permalink/<user_token>
RESPONSES 201 Created, 404 Not Found, 410 Gone, 503 Service Unavailable

Returns the same response as POST /rooms.

Example response

{
    "access_key": "aQrgsTQUn7HPZwncdFyolFNk",
    "ready": false,
    "locked": false,
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "ready": false,
        "started_at": "2024-05-14T13:44:54.436Z",
        "shutdown": false,
        "guest_token": "7dP90FgGlq39y4p9WqwhiyaL"
    },
    "team": {
        "name": "Test"
    },
    "user": {
        "id": "66436ad6858f54f55edef729",
        "room_id": "6643685b858f54f55edef723",
        "name": "Jane Doe",
        "avatar": null,
        "guest": false,
        "blocked": false,
        "ready": false
    },
    "links": {
        "self": "https://api.eyeson.team/rooms/aQrgsTQUn7HPZwncdFyolFNk",
        "gui": "https://app.eyeson.team/?aQrgsTQUn7HPZwncdFyolFNk",
        "guest_join": "https://app.eyeson.team/?guest=7dP90FgGlq39y4p9WqwhiyaL",
        "websocket": "https://api.eyeson.team/rt?access_key=aQrgsTQUn7HPZwncdFyolFNk"
    },
    "options": {
        "show_names": true,
        "show_label": true,
        "exit_url": null,
        "recording_available": true,
        "broadcast_available": true,
        "layout_available": true,
        "layout": "auto",
        "reaction_available": true,
        "suggest_guest_names": true,
        "lock_available": false,
        "kick_available": true,
        "sfu_mode": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "playbacks": [],
    "presentation": null,
    "broadcasts": [],
    "recording": null,
    "snapshots": [],
    "waiting_list": [],
    "signaling": {
        "type": "sepp",
        "options": {
            ...
        }
    }
}

Register guest user

Register any guest user when the meeting is up and running via the permalink's guest_token. Use the same endpoint as register guest user.

POST /guests/<guest_token>
RESPONSES 201 CREATED, 400 BAD REQUEST, 410 GONE, 423 LOCKED

Example response

{
    "access_key": "9vevGllYKQ66LR8bV6u4Ygfe",
    "ready": false,
    "locked": false,
    "room": {
        "id": "6643685b858f54f55edef723",
        "name": "Test",
        "ready": false,
        "started_at": "2024-05-14T13:48:09.741Z",
        "shutdown": false,
        "guest_token": "VlokZmDfi6AvKseeKGrwUft6"
    },
    "team": {
        "name": "Test"
    },
    "user": {
        "id": "66436ba1858f54f55edef72c",
        "room_id": "6643685b858f54f55edef723",
        "name": "Guest",
        "avatar": null,
        "guest": true,
        "blocked": false,
        "ready": false
    },
    "links": {
        "self": "https://api.eyeson.team/rooms/9vevGllYKQ66LR8bV6u4Ygfe",
        "gui": "https://app.eyeson.team/?9vevGllYKQ66LR8bV6u4Ygfe",
        "guest_join": "https://app.eyeson.team/?guest=VlokZmDfi6AvKseeKGrwUft6",
        "websocket": "https://api.eyeson.team/rt?access_key=9vevGllYKQ66LR8bV6u4Ygfe"
    },
    "options": {
        "show_names": true,
        "show_label": true,
        "exit_url": null,
        "recording_available": true,
        "broadcast_available": true,
        "layout_available": true,
        "layout": "auto",
        "reaction_available": true,
        "suggest_guest_names": true,
        "lock_available": false,
        "kick_available": true,
        "sfu_mode": "ptp",
        "layout_users": null,
        "layout_name": null,
        "layout_map": null,
        "voice_activation": false,
        "custom_fields": {},
        "widescreen": true,
        "background_color": "#121212"
    },
    "playbacks": [],
    "presentation": null,
    "broadcasts": [],
    "recording": null,
    "snapshots": [],
    "waiting_list": [],
    "signaling": {
        "type": "sepp",
        "options": {
            ...
        }
    }
}

Create permalink​

expires_at​

user[id]​

user[name]​

options[exit_url]​

options[recording_available]​

options[widescreen]​

options[custom_fields][locale]​

Example response​

Get list of permalinks​

page​

limit​

expired​

Example response​

Get specific permalink by Id​

Example response​

Update permalink​

Delete permalink​

Register host user to permalink​

Example response​

Remove host user from permalink​

Meeting information​

Example response​

Start meeting from permalink​

Example response​

Register guest user​

Example response​

Create permalink

expires_at

user[id]

user[name]

options[exit_url]

options[recording_available]

options[widescreen]

options[custom_fields][locale]

Example response

Get list of permalinks

page

limit

expired

Example response

Get specific permalink by Id

Example response

Update permalink

Delete permalink

Register host user to permalink

Example response

Remove host user from permalink

Meeting information

Example response

Start meeting from permalink

Example response

Register guest user

Example response