Create Turn Server Project

Use this endpoint to create a new TURN Server Project, which can have an optional quota, notification settings, and a unique API key.

POST

https://<appname>.metered.live/api/v2/turn/project?secretKey=<YOUR_SECRET_KEY>

<appname> - Replace with the name of your app.
<YOUR_SECRET_KEY> - Your secret key, found in the Dashboard → Developers → Secret Key.

---

Request

POST /api/v2/turn/project?secretKey=<YOUR_SECRET_KEY>

Body Parameters

Parameter	Type	Required	Description
projectName	String	Yes	Unique name for the project. Must be fewer than 100 characters.
quotaInBytes	Number	No	Data usage quota in bytes for the project. Must be an integer ≥ 1 MiB (1048576). If omitted or set to 0, no quota is enforced (usage is still tracked).
webhookUrl	String	No	An HTTPS endpoint (must start with https://). If set, the system will send a POST request to this URL when the project quota is reached.
notificationEmails	Array	No	An array of valid email addresses (max 10). These will receive notifications when usage meets or exceeds the quota (if a quota is set).
quotaExceededAction	String	No	Action taken when the project quota is reached. Supported values: notify, none or disable. Defaults to disable if not specified.

Example Request Body

{
  "projectName": "MyProject",
  "quotaInBytes": 1073741824,
  "webhookUrl": "https://example.com/webhook/turn-usage",
  "notificationEmails": ["ops@example.com", "admin@example.com"],
  "quotaExceededAction": "disable"
}

---

Responses

Success Response

Field	Type	Description
_id	String	Unique identifier for the newly created project.
projectName	String	The project name you provided.
quotaInBytes	Number	The usage quota in bytes. Returns 0 if no quota was specified.
webhookUrl	String	The configured webhook URL, or null if none was provided.
notificationEmails	Array	The list of email addresses that will receive notifications.
quotaExceededAction	String	The action the system will take when the quota is reached (NOTIFY_ONLY or DISABLE).
apiKey	String	The unique API key for this project. Use this key to create and manage TURN credentials under this project.
created	String	Timestamp (ISO 8601) indicating when the project was created.

HTTP Status: 200 OK

Example Success Response

{
  "_id": "63fdb9f998c1abec0bd3e16c",
  "projectName": "MyProject",
  "quotaInBytes": 1073741824,
  "webhookUrl": "https://example.com/webhook/turn-usage",
  "notificationEmails": ["ops@example.com", "admin@example.com"],
  "quotaExceededAction": "disable",
  "apiKey": "pk_abc123xyz",
  "created": "2025-01-24T10:15:00.000Z"
}

---

Error Responses

HTTP Status	Message	Description
400	invalid secretKey app not found	The secretKey is invalid; no matching app found.
400	Invalid request. Not subscribed to any turn server plan	The app is not subscribed to a TURN server plan.
400	Project name must be a string of less than 100 characters	Invalid or missing projectName.
400	Invalid quota, must be an integer greater than 1 MiB (1048576)	quotaInBytes is malformed or smaller than 1 MiB.
400	Webhook URL must be a string or Webhook URL must start with https://	The webhookUrl is invalid or not HTTPS.
400	Notification emails must be an array	notificationEmails was not provided as an array.
400	Invalid email address	One or more emails in notificationEmails is invalid.
400	Notification emails must not exceed 10	Too many emails were provided.
400	Invalid quotaExceededAction, it should be one of: ...	The specified quotaExceededAction is not recognized.

---

Code Examples

cURL

curl -X POST "https://<appname>.metered.live/api/v2/turn/project?secretKey=<YOUR_SECRET_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "projectName": "MyProject",
    "quotaInBytes": 1073741824,
    "webhookUrl": "https://example.com/webhook/turn-usage",
    "notificationEmails": ["ops@example.com","admin@example.com"],
    "quotaExceededAction": "notify"
  }'

JavaScript (Fetch)

fetch(
  `https://<appname>.metered.live/api/v2/turn/project?secretKey=<YOUR_SECRET_KEY>`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      projectName: "MyProject",
      quotaInBytes: 1073741824,
      webhookUrl: "https://example.com/webhook/turn-usage",
      notificationEmails: ["ops@example.com", "admin@example.com"],
      quotaExceededAction: "notify",
    }),
  }
)
  .then((response) => response.json())
  .then((data) => console.log("Project Created:", data))
  .catch((error) => console.error("Error:", error));