Quickstart: create your first room

This walkthrough takes you from nothing to a working video room in a few minutes: get a token, create a room, open the join links, and close the room when you're done.

1. Obtain a token

Either token type can create rooms. Which one you use decides who owns the room afterwards: an Organization API Token creates the room inside its own organization and can manage it from then on, while an Instance API Token creates a room that belongs to no organization.

If you are integrating on behalf of a single organization, take the Organization API Token:

1. Log in as an organization owner.
2. Open the Integrations page.
3. Copy the token from the API section.

For tenant-wide access, take an Instance API Token instead:

1. Log in as an admin user into the MeetOne application.
2. Navigate to the API Tokens section via the side menu, or directly at https://acme.meetone.io/admin_ng/api_tokens.
3. Create a token, giving it a name and an expiry date.
4. Copy the token from the details page.

Export it as an environment variable so it's easy to reuse in the examples below:

export MEETONE_API_TOKEN="eyJhbGciOiJIUzI1****"

See Authentication & API tokens for the full picture of what each token type can do.

2. Create a room

Send a POST request to /api/rooms with the required fields name, meeting_duration (in minutes), and scheduled_at:

curl -X POST "https://acme.meetone.io/api/rooms" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My new room",
    "meeting_duration": 45,
    "scheduled_at": "2024-08-23T15:19:36.378+02:00"
  }'

A successful request returns 201 Created with the created room:

{
  "name": "My new room",
  "token": "f167d6f76f14991c",
  "status": "active",
  "access_token": "65a56167f28f6dec",
  "guest_token": "2367668999959557",
  "scheduled_at": "2024-08-23T15:19:36.378+02:00",
  "meeting_duration": 45,
  "return_url": "http://example.com/rooms/login",
  "host_join_url": "http://www.example.com/r/7bbb22b73d4e4732",
  "guest_join_url": "http://www.example.com/r/3d4e4722b7327bbb",
  "enable_chat": true,
  "enable_screenshare": true,
  "enable_invites": true,
  "permanent": false,
  "created_at": "2024-08-23T15:19:36.378+02:00",
  "updated_at": "2024-08-23T15:19:36.378+02:00"
}

Keep the token value — you'll need it to close the room later. If any required field is missing or invalid, the API responds with 400 Bad Request and a list of validation errors; see Errors & pagination.

3. Open the join links

The response contains two distinct join URLs:

• host_join_url — for the host running the consultation.
• guest_join_url — share this with the guest joining the call.

Both URLs accept a name query parameter to pre-fill the participant's display name, for example ?name=John+Smith.

4. Close the room when you're done

Once the call is over, close the room using its token (not access_token):

curl -X PUT "https://acme.meetone.io/api/rooms/f167d6f76f14991c/close" \
  -H "Authorization: Bearer $MEETONE_API_TOKEN"

A successful close returns 204 No Content. A closed room can no longer be accessed. If you forget to close a room, a periodic cleanup job also closes any room whose scheduled_at is more than 24 hours in the past — but explicitly closing rooms when you know a call has ended is recommended.

Next steps

• Rooms endpoints — full CRUD reference.
• Room lifecycle — states a room moves through and how closing works in detail.
• Errors & pagination — interpreting error responses.

Related

• Authentication & API tokens
• Rooms endpoints
• Room lifecycle

Questions? Contact us at support@meetone.io.