Reference

Platform API Reference

Overview

The Platform API provides a set of HTTP endpoints that allow you to interact with the MAF Platform. This includes managing user authentication, handling rooms, and monitoring apps.

All endpoints are RESTful and return JSON responses. Parameters are passed via the URL path, query string, and/or request body as appropriate.

For TypeScript servers, you can use the @usemaf/platform package to interact with the Platform API more easily. The package provides type definitions, helper functions, and classes to simplify making requests and handling responses.

Authentication

Platform API endpoints are authenticated using the Authorization header. When making requests, include a base64 encoded string of your client ID and secret in the format Basic <base64(clientId:clientSecret)>.

You will need to pass in the app slug and organization slug of the app you are interacting with in the URL path. The documentation will refer to these as :app and :org respectively.

If a request is not authenticated or if authentication is incorrect, you will receive a 401 Unauthorized response.

App Endpoints

GET /api/v1/apps/:org/:app/rooms

Lists all the rooms.

Example Response

[
  {
    // A UUID for the room.
    "id": "b7276f46-7456-4f01-a7ec-cb4103372966",
    // A 64-character secret key used for your server to verify certain requests.
    "secret": "iMcbVmiaEJ9YEETIZeDafaG3oAQslb4G4yIiJsXe9mWw5IbKgVGVhz7TKJgkbXtw",
    // Another key that can be used for room identification. Developer-defined.
    "key": "ABCDEF",
    // Metadata associated with the room. This is defined by the developer.
    // See the "Meta" page for more details.
    "meta": {
      "owner_id": "f2c6539f-c2ff-4f84-a40b-157ce2e20552",
      "status": "WAITING"
    }
  },
  {
    "id": "9f2a1508-0b68-48b7-b3d7-617ee5fdd1f9",
    "secret": "9b1c2f3e4d5a6b7c8d9e0f1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u",
    "key": "GHIJKL",
    "meta": {
      "owner_id": "1510d3cc-44a0-4a62-bcca-1a8e55f45cbd",
      "status": "IN_PROGRESS"
    }
  }
  // ...
]

POST /api/v1/apps/:org/:app/rooms

Creates a new room.

Example Request Body

{
  // <Optional> A key used to identify the room. If not provided, the room ID
  // will be used. Must be unique within the app. The key must be less than
  // or equal to 128 characters long and cannot be "default" or a UUID.
  "key": "ABCD1234",
  // <Optional> Metadata associated with the room. This can be any key-value
  // pairs defined by the developer.
  "meta": {
    "owner_id": "f2c6539f-c2ff-4f84-a40b-157ce2e20552",
    "status": "WAITING"
  }
}