REST quickstart

This guide uses JavaScript fetch to call the REST API directly, without the SDK. You can make the same requests from other languages. The examples run on your server. apiKey is your organization API key, loaded from secure configuration.

List available labs

Request your organization’s lab catalog:

const response = await fetch('https://api.cybr.com/api/v2/labs', {
  headers: { 'X-API-Key': apiKey }
})

if (!response.ok) {
  throw new Error(`Cannot load labs: ${response.status}`)
}

const labs = await response.json()

Each lab has an id. Your application uses that ID to request a deployment.

Launch a lab

Your application supplies the selected labId and the current learner’s learnerId. Membership comes from your application’s access policy.

const response = await fetch('https://api.cybr.com/api/v2/deployments', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ labId, learnerId, membership: 'free' })
})

if (!response.ok) {
  const error = await response.json()
  throw new Error(error.message ?? `Lab launch failed: ${response.status}`)
}

const { deploymentId } = await response.json()

Save deploymentId with the learner’s session. Your application uses it to check status and end this deployment. The response means that Cybr accepted the launch request. The lab environment takes time to become ready.

Check when the lab is ready

Request the deployment status about every five seconds while it is loading:

const response = await fetch(
  `https://api.cybr.com/api/v2/deployments/${encodeURIComponent(deploymentId)}`,
  { headers: { 'X-API-Key': apiKey } }
)

if (!response.ok) {
  throw new Error(`Cannot read lab status: ${response.status}`)
}

const status = await response.json()

if (status.status === 'complete') {
  // Show status.outputs as connection details for this learner.
} else if (status.status === 'failed') {
  // Stop polling and show that the lab is unavailable.
} else {
  // Check again after about five seconds.
}

A complete status means that the environment is ready. It does not mean that the learner completed the exercise. Your application controls the polling schedule and timeout. A page refresh can resume status checks with the saved deployment ID. Connection details can contain credentials. Your server must check that the current learner owns the deployment before it returns those details.

End the lab

When the learner chooses to end the lab, send a teardown request:

const response = await fetch(
  `https://api.cybr.com/api/v2/deployments/${encodeURIComponent(deploymentId)}/destroy`,
  {
    method: 'POST',
    headers: { 'X-API-Key': apiKey }
  }
)

if (!response.ok) {
  throw new Error(`Cannot end lab: ${response.status}`)
}

The request starts teardown. It does not record learner completion.

Next steps

These examples cover the request flow. A production integration also handles rate limits, timeouts, and uncertain outcomes after interrupted requests. The REST overview links to the OpenAPI download and error details. The completion guide explains completion and CTF verification.

REST API setup

REST API endpoints

Web terminal protocol

List available labs

Launch a lab

Check when the lab is ready

End the lab

Next steps

​List available labs

​Launch a lab

​Check when the lab is ready

​End the lab

​Next steps

List available labs

Launch a lab

Check when the lab is ready

End the lab

Next steps