Welcome to our Developer API.
Jibris On Demand (JOD) helps you setup Scalable Recording and Live Streaming for your Jitsi Meet Instance.
Getting Started
To setup JOD, you will need to have Jitsi setup on a self-hosted server. Afterwards, all you need to do is create or own an account on Jibris On Demand. From there the process is as simple as completing your project and domain configuration. This will enabled you to deploy recorders using our authenticated dashboard or developer API.
NB: You will have to complete your domain configuration before you can deploy recorders with this developer API (See error section for "Deploy Recorder")
Authentication
Securing and authenticating your requests on JOD is pretty simple and straight forward. Simple grab your API KEY (Which can be found on your dashboard, as seen below).
This API KEY must be kept secret and should not be exposed or revealed on the client side of your applications. It is meant to be used and consumed from the server side. If at any point in time you feel your security has been compromised, immediately login to your dashboard and generate a new API KEY (as shown above)
HTTP response codes
- 200 — Success Everything went smooth.
- 204 — No Results Found Request successful but no content was found.
- 401 — Unauthorised Missing or incorrect API Key.
- 402 — Not Enough Balance Client doesn't have enough balance to deploy recorders.
- 406 — Incomplete Configuration Client's Jitsi domain configuration is not completed to enable deployment.
- 500 — Internal Server Error This is an issue with JOD's servers processing your request. In most cases the message is lost during the process, and we are notified so that we can investigate the issue.
- 503 — Service Unavailable During planned service outages, JOD API services will return this HTTP response and associated JSON body.
API Response
All response sent from the JOD server comes in a JSON format containing the following details:
{
it : "worked",
message : "request sent successfully"
}
The it field can be used to programmatically detect if the request was successful or failed. Here are the supported states:
- "worked" Everything went smooth.
- "failed" Something went wrong.
The message field can be used to get more information about the request.
Deploy Recorders
This endpoint is responsible for deploying recorders for your Jitsi domain.
Endpoint
https://api.jod.sh/deploy-recorder
Parameters (Body format)
| apiKey | string | REQUIRED API Key of the account. This can be found on the project page. |
| domain | string | REQUIRED Your configured domain eg. call.myjitsidomain.com |
| recorders | integer | REQUIRED Number of recorders to deploy for your Jitsi. |
| duration | integer | REQUIRED How long the recorders should be available for in hours. |
| location | string | REQUIRED The location for your recorder, eg. ams for Amsterdam, Netherlands. Below is the list of available locations options:
|
| callback_url | string | REQUIRED Callback URL to receive response when the recorder deployment is successful or failed. |
| jibri_version | string | OPTIONAL What jibri configuration to deploy, eg. new for New configuration (stream to multiple RTMP servers). Below is the available options:
|
| finalize_script | string | OPTIONAL What finalize script to use on the Jibri server, eg. default for finalize script provided by JOD. Below is the available options:
|
Example request with Javascript
Method: POST
NB The POST Request Content-Type is x-www-form-urlencoded
const axios = require("axios");
const qs = require("querystring");
const requestBody = {
apiKey: "JOD-3c4708cf-dc4c-4166-9cc3-ba483f6b7f6b",
domain: "meet.lindeas.com",
recorders: "28",
duration: "3",
location: "blr",
finalize_script: "custom",
jibri_version: "new",
callback_url: "https://api.mydomain/deployed-recorder",
};
const config = {
headers: {
"Content-Type": "application/x-www-form-urlencoded",
},
};
axios
.post("https://api.jod.sh/deploy-recorder", qs.stringify(requestBody), config)
.then((result) => {
// handle the response body
console.dir(result);
})
.catch((err) => {
// handle the error
console.dir(err);
});
Example request with Curl
Method: POST
NB The POST Request Content-Type is x-www-form-urlencoded
curl --location --request POST 'https://api.jod.sh/deploy-recorder' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'apiKey=JOD-7c2dedb0-787c-4233-a67e-eb9167b62037' \
--data-urlencode 'domain=yourjitsidomain.com' \
--data-urlencode 'recorders=2' \
--data-urlencode 'duration=1' \
--data-urlencode 'location=lon' \
--data-urlencode 'finalize_script=custom' \
--data-urlencode 'jibri_version=new' \
--data-urlencode 'callback_url=https://yourdomain.com/callback'
Success Response
{
it : "worked",
message : "your deployment will join your jitsi soon"
balance : 13.60
deployment_id : "wedsas-ewfzasfe-zdcxcv-sefe"
}
Error Response
{
it : "failed",
message : "invalid API Key"
}
Callback Response
Callback response is in JSON format and it is sent as a POST request. Below are the type of response that is sent to your callback URL.
Callback Code Sample
var express = require('express');
var bodyParser = require('body-parser');
var app = express();
app.use(bodyParser.json());
app.post('/callback_url', function(request, response){
console.log(request.body); //get callback response
});
app.listen(3000);
$data = json_decode(file_get_contents('php://input'), true);
print_r($data); //get callback response
Success Response
{
it : "worked",
message : "deployment successful",
deployment_info : {
deployment_id : "wedsas-ewfzasfe-zdcxcv-sefe",
recorders : [
{
recorder_id : "sdsd-edscedadc-sdsd-fsdf-sdfe",
recorder_ip : "76.34.23.222"
},
{
recorder_id : "fiei-fesddfe-sdx-degrte-redse",
recorder_ip : "87.23.123.43"
}
]
}
}
Failed Response
{
it : "failed",
message : "recorders not available in specified location"
}
Get Recordings
This endpoint is responsible for getting recordings for your Jitsi calls.
Endpoints
https://api.jod.sh/get-room-recordings //get recordings by room name
https://api.jod.sh/get-all-recordings //get all recordings by domain
Parameters (Body format)
| apiKey | string | REQUIRED API Key of the account. This can be found on the project page. |
| domain | string | REQUIRED Your configured domain eg. call.myjitsidomain.com |
| room | integer | REQUIRED Jitsi call room name. Note: this is required when using the get recordings by room name endpoint. |
Example request with Javascript
Method: POST
NB The POST Request Content-Type is x-www-form-urlencoded
const axios = require("axios");
const qs = require("querystring");
const requestBody = {
apiKey: "JOD-3c4708cf-dc4c-4166-9cc3-ba483f6b7f6b",
domain: "meet.lindeas.com",
room: "checkin03",
};
const config = {
headers: {
"Content-Type": "application/x-www-form-urlencoded",
},
};
axios
.post("https://api.jod.sh/get-room-recordings", qs.stringify(requestBody), config)
.then((result) => {
// handle the response body
console.dir(result);
})
.catch((err) => {
// handle the error
console.dir(err);
});
Example request with Curl
Method: POST
NB The POST Request Content-Type is x-www-form-urlencoded
curl --location --request POST 'https://api.jod.sh/get-room-recordings' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'apiKey=JOD-7c2dedb0-787c-4233-a67e-eb9167b62037' \
--data-urlencode 'domain=yourjitsidomain.com' \
--data-urlencode 'room=checkin03'
Success Response
{
it : "worked",
message : "recordings found"
total_recordings : 2
recordings : [
{
room: "checkin03",
url: "https://jod-recordings.s3.eu-central-1.amazonaws.com/425b4cb5-05bf-4b7a-9e60-kjshdfkjehfn/checkin03/checkin03_2020-10-11-16-07-05.mp4",
created_at: "2020-10-11T16:11:55.000Z"
},
{
room: "checkin03",
url: "https://jod-recordings.s3.eu-central-1.amazonaws.com/425b4cb5-05bf-4b7a-9e60-kjshdfkjehfn/checkin03/checkin03_2020-10-11-20-07-05.mp4",
created_at: "2020-10-11T20:11:55.000Z"
}
]
deployment_id : "wedsas-ewfzasfe-zdcxcv-sefe"
}
Error Response
{
it : "failed",
message : "invalid API Key"
}