Permalink API

Permalink API is used to pre-define meeting rooms, get sharable guest links, and to start meetings whenever needed.

Meeting room settings can be updated at any time.

info

API host 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].

Parameters	Type	Description
expires_at	ISO8601 Timestamp (optional)	Optional Timestamp when permalink meetings can no longer be started. E.g. 2024-05-15T10:00:00.000Z
user[id]	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]	String (required)	Display name of the user.
options[exit_url]	String (optional)	Exit destination, URL for exit button in GUI
options[recording_available]	Boolean (optional)	Allow recordings. Default: true
options[widescreen]	Boolean (optional)	Run meeting in widescreen mode (16:9 aspect ratio). Default: false
options[custom_fields][locale]	Language Code (optional)	User preferred language code (en, de, fr).
and	many	more...

All parameters as of Start meeting.

Heads up!

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"
    }
}

note

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

Parameters	Type	Description
page	Integer (optional)	Fetch next set of permalinks
limit	Integer (optional)	defaults to 25
expired	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

caution

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.

caution

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/permalink/?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": {
            ...
        }
    }
}

Permalink API

Create permalink​

Get list of permalinks​

Get specific permalink by Id​

Update permalink​

Delete permalink​

Register host user to permalink​

Remove host user from permalink​

Meeting information​

Start meeting from permalink​

Register guest user​

Create permalink

Get list of permalinks

Get specific permalink by Id

Update permalink

Delete permalink

Register host user to permalink

Remove host user from permalink

Meeting information

Start meeting from permalink

Register guest user