OpenCue REST API Reference

Complete API reference for the OpenCue REST Gateway endpoints, authentication, and data formats.

Table of contents

1. Overview
   1. Base Information
   2. Authentication
2. Authentication
   1. JWT Token Requirements
   2. Token Creation Example
   3. Error Responses
3. Interface Overview
4. Show Interface
   1. Get All Shows
   2. Find Show
   3. Create Show
5. Job Interface
   1. Get Jobs
   2. Find Job
   3. Get Job Frames
   4. Pause Job
   5. Resume Job
   6. Kill Job
6. Frame Interface
   1. Get Frame
   2. Retry Frame
   3. Kill Frame
   4. Eat Frame
7. Layer Interface
   1. Get Layer
   2. Find Layer
   3. Get Layer Frames
   4. Kill Layer
8. Host Interface
   1. Get All Hosts
   2. Find Host
   3. Get Host
   4. Lock Host
   5. Unlock Host
9. Group Interface
   1. Find Group
   2. Get Group
   3. Set Minimum Cores
   4. Set Maximum Cores
10. Owner Interface
    1. Get Owner
    2. Set Maximum Cores
    3. Take Ownership
11. Proc Interface
    1. Get Process
    2. Kill Process
    3. Unbook Process
12. Deed Interface
    1. Get Deed Owner
    2. Get Deed Host
13. Data Types
    1. Common Types
       1. Job States
       2. Frame States
       3. Host Lock States
    2. Request/Response Objects
       1. Job Object
       2. Frame Object
       3. Host Object
14. Error Handling
    1. Error Response Format
    2. Common Error Codes
    3. HTTP Status Codes
15. Rate Limiting
16. Best Practices
    1. Performance
    2. Security
    3. Reliability
17. SDK Examples
    1. Python Client
    2. JavaScript Client
18. What’s next?

---

Overview

The OpenCue REST Gateway provides HTTP/REST endpoints for all OpenCue gRPC interfaces. It converts HTTP requests to gRPC calls and returns JSON responses, enabling web applications and HTTP clients to interact with OpenCue services.

Base Information

• Base URL: http://your-gateway:8448 (configurable)
• Protocol: HTTP/HTTPS
• Authentication: JWT Bearer tokens
• Request Method: POST (for all endpoints)
• Content Type: application/json
• Response Format: JSON

Authentication

All endpoints require JWT authentication:

POST /interface.Interface/Method
Authorization: Bearer <jwt-token>
Content-Type: application/json

---

Authentication

JWT Token Requirements

• Algorithm: HMAC SHA256 (HS256)
• Required Claims: sub (subject), exp (expiration)
• Header Format: Authorization: Bearer <token>

Token Creation Example

import jwt
import time

def create_token(secret, user_id):
    payload = {
        'sub': user_id,
        'exp': int(time.time()) + 3600  # 1 hour
    }
    return jwt.encode(payload, secret, algorithm='HS256')

Error Responses

Status Code	Description
401	Missing or invalid Authorization header
403	Token validation failed or expired
500	Internal server error

---

Interface Overview

The REST API provides access to 9 core OpenCue interfaces:

Interface	Purpose	Key Endpoints
Show Interface	Show management	GetShows, FindShow, CreateShow
Job Interface	Job operations	GetJobs, FindJob, Kill, Pause, Resume
Frame Interface	Frame management	GetFrame, Kill, Retry, Eat
Layer Interface	Layer operations	GetLayer, FindLayer, Kill
Group Interface	Host groups	FindGroup, GetGroup, SetMinCores, SetMaxCores
Host Interface	Host management	GetHosts, FindHost, Lock, Unlock
Owner Interface	Ownership	GetOwner, SetMaxCores, TakeOwnership
Proc Interface	Process monitoring	GetProc, Kill, Unbook
Deed Interface	Resource deeds	GetOwner, GetHost

---

Show Interface

Manage shows (projects) in OpenCue.

Get All Shows

Get a list of all shows in the system.

POST /show.ShowInterface/GetShows

Request Body:

{}

Response:

{
  "shows": {
    "shows": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "myshow",
        "defaultMinCores": 1,
        "defaultMaxCores": 100,
        "commentEmail": "",
        "bookingEnabled": true,
        "dispatchEnabled": true,
        "active": true,
        "showStats": {
          "runningFrames": 5,
          "deadFrames": 0,
          "pendingFrames": 10,
          "pendingJobs": 2
        },
        "defaultMinGpus": 0,
        "defaultMaxGpus": 10
      }
    ]
  }
}

Find Show

Find a specific show by name.

POST /show.ShowInterface/FindShow

Request Body:

{
  "name": "myshow"
}

Response:

{
  "show": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "myshow",
    "defaultMinCores": 1,
    "defaultMaxCores": 100,
    "active": true
  }
}

Create Show

Create a new show.

POST /show.ShowInterface/CreateShow

Request Body:

{
  "name": "newshow",
  "defaultMinCores": 1,
  "defaultMaxCores": 50
}

Response:

{
  "show": {
    "id": "new-show-id",
    "name": "newshow",
    "defaultMinCores": 1,
    "defaultMaxCores": 50,
    "active": true
  }
}

---

Job Interface

Manage rendering jobs and their lifecycle.

Get Jobs

Retrieve jobs for a show with optional filtering.

POST /job.JobInterface/GetJobs

Request Body:

{
  "r": {
    "show": {
      "name": "myshow"
    },
    "includeFinished": false,
    "maxResults": 100
  }
}

Response:

{
  "jobs": {
    "jobs": [
      {
        "id": "job-id-123",
        "name": "myshow-shot001-comp",
        "state": "PENDING",
        "shot": "shot001",
        "show": "myshow",
        "user": "artist1",
        "group": "comp",
        "facility": "cloud",
        "priority": 100,
        "minCores": 1,
        "maxCores": 10,
        "isPaused": false,
        "hasComment": false,
        "startTime": 1694000000,
        "stopTime": 0,
        "jobStats": {
          "runningFrames": 0,
          "deadFrames": 0,
          "pendingFrames": 25,
          "succeededFrames": 0,
          "totalFrames": 25
        }
      }
    ]
  }
}

Find Job

Find a specific job by name.

POST /job.JobInterface/FindJob

Request Body:

{
  "name": "myshow-shot001-comp"
}

Get Job Frames

Retrieve frames for a specific job.

POST /job.JobInterface/GetFrames

Request Body:

{
  "job": {
    "id": "job-id-123"
  },
  "req": {
    "includeFinished": true,
    "page": 1,
    "limit": 100
  }
}

Response:

{
  "frames": {
    "frames": [
      {
        "id": "frame-id-456",
        "name": "0001-layer_name",
        "layerName": "comp_layer",
        "number": 1,
        "state": "WAITING",
        "retryCount": 0,
        "exitStatus": -1,
        "startTime": 0,
        "stopTime": 0,
        "maxRss": "0",
        "usedMemory": "0",
        "lastResource": "/0.00/0"
      }
    ]
  }
}

Pause Job

Pause a running or pending job.

POST /job.JobInterface/Pause

Request Body:

{
  "job": {
    "id": "job-id-123"
  }
}

Response:

{}

Resume Job

Resume a paused job.

POST /job.JobInterface/Resume

Request Body:

{
  "job": {
    "id": "job-id-123"
  }
}

Kill Job

Terminate a job and all its frames.

POST /job.JobInterface/Kill

Request Body:

{
  "job": {
    "id": "job-id-123"
  }
}

---

Frame Interface

Manage individual frame operations.

Get Frame

Retrieve detailed information about a specific frame.

POST /frame.FrameInterface/GetFrame

Request Body:

{
  "id": "frame-id-456"
}

Response:

{
  "frame": {
    "id": "frame-id-456",
    "name": "0001-layer_name",
    "layerName": "comp_layer",
    "number": 1,
    "state": "SUCCEEDED",
    "retryCount": 0,
    "exitStatus": 0,
    "startTime": 1694000000,
    "stopTime": 1694000300,
    "maxRss": "2147483648",
    "usedMemory": "1073741824",
    "totalCoreTime": 300
  }
}

Retry Frame

Retry a failed frame.

POST /frame.FrameInterface/Retry

Request Body:

{
  "frame": {
    "id": "frame-id-456"
  }
}

Kill Frame

Kill a running frame.

POST /frame.FrameInterface/Kill

Request Body:

{
  "frame": {
    "id": "frame-id-456"
  }
}

Eat Frame

Mark a frame as completed (skip rendering).

POST /frame.FrameInterface/Eat

Request Body:

{
  "frame": {
    "id": "frame-id-456"
  }
}

---

Layer Interface

Manage job layers and their properties.

Get Layer

Retrieve layer information.

POST /layer.LayerInterface/GetLayer

Request Body:

{
  "id": "layer-id-789"
}

Response:

{
  "layer": {
    "id": "layer-id-789",
    "name": "comp_layer",
    "type": "Render",
    "isEnabled": true,
    "minimumCores": 1,
    "maximumCores": 4,
    "minimumMemory": 2147483648,
    "layerStats": {
      "totalFrames": 25,
      "runningFrames": 0,
      "deadFrames": 0,
      "pendingFrames": 25,
      "succeededFrames": 0
    }
  }
}

Find Layer

Find a layer within a job.

POST /layer.LayerInterface/FindLayer

Request Body:

{
  "job": {
    "id": "job-id-123"
  },
  "layer": "comp_layer"
}

Get Layer Frames

Get all frames for a specific layer.

POST /layer.LayerInterface/GetFrames

Request Body:

{
  "layer": {
    "id": "layer-id-789"
  },
  "req": {
    "page": 1,
    "limit": 100
  }
}

Kill Layer

Kill all frames in a layer.

POST /layer.LayerInterface/Kill

Request Body:

{
  "layer": {
    "id": "layer-id-789"
  }
}

---

Host Interface

Manage render hosts and their resources.

Get All Hosts

Retrieve all hosts in the render farm.

POST /host.HostInterface/GetHosts

Request Body:

{}

Response:

{
  "hosts": {
    "hosts": [
      {
        "id": "host-id-abc",
        "name": "render-node-01",
        "lockState": "OPEN",
        "bootTime": 1694000000,
        "pingTime": 1694001000,
        "os": "linux",
        "totalCores": 16,
        "idleCores": 12,
        "totalMemory": 68719476736,
        "freeMemory": 34359738368,
        "totalGpus": 2,
        "freeGpus": 2,
        "hostStats": {
          "totalFrames": 4,
          "runningFrames": 4
        }
      }
    ]
  }
}

Find Host

Find a specific host by name.

POST /host.HostInterface/FindHost

Request Body:

{
  "name": "render-node-01"
}

Get Host

Get detailed host information.

POST /host.HostInterface/GetHost

Request Body:

{
  "id": "host-id-abc"
}

Lock Host

Prevent new jobs from being assigned to a host.

POST /host.HostInterface/Lock

Request Body:

{
  "host": {
    "id": "host-id-abc"
  }
}

Unlock Host

Allow jobs to be assigned to a host.

POST /host.HostInterface/Unlock

Request Body:

{
  "host": {
    "id": "host-id-abc"
  }
}

---

Group Interface

Manage resource groups and allocation.

Find Group

Find a group within a show.

POST /group.GroupInterface/FindGroup

Request Body:

{
  "show": {
    "name": "myshow"
  },
  "name": "comp"
}

Response:

{
  "group": {
    "id": "group-id-def",
    "name": "comp",
    "department": "compositing",
    "defaultJobPriority": 100,
    "defaultJobMinCores": 1,
    "defaultJobMaxCores": 8,
    "groupStats": {
      "runningFrames": 5,
      "deadFrames": 0,
      "pendingFrames": 20,
      "pendingJobs": 3
    }
  }
}

Get Group

Get detailed group information.

POST /group.GroupInterface/GetGroup

Request Body:

{
  "id": "group-id-def"
}

Set Minimum Cores

Set minimum core allocation for a group.

POST /group.GroupInterface/SetMinCores

Request Body:

{
  "group": {
    "id": "group-id-def"
  },
  "cores": 4
}

Set Maximum Cores

Set maximum core allocation for a group.

POST /group.GroupInterface/SetMaxCores

Request Body:

{
  "group": {
    "id": "group-id-def"
  },
  "cores": 16
}

---

Owner Interface

Manage resource ownership and allocation.

Get Owner

Get owner information and resource allocation.

POST /owner.OwnerInterface/GetOwner

Request Body:

{
  "name": "artist1"
}

Response:

{
  "owner": {
    "name": "artist1",
    "maxCores": 20,
    "minCores": 2,
    "maxGpus": 4,
    "minGpus": 0,
    "ownerStats": {
      "runningFrames": 8,
      "maxFrames": 50
    }
  }
}

Set Maximum Cores

Set maximum core allocation for an owner.

POST /owner.OwnerInterface/SetMaxCores

Request Body:

{
  "owner": {
    "name": "artist1"
  },
  "cores": 32
}

Take Ownership

Take ownership of a host.

POST /owner.OwnerInterface/TakeOwnership

Request Body:

{
  "host": {
    "id": "host-id-abc"
  },
  "owner": {
    "name": "artist1"
  }
}

---

Proc Interface

Manage running processes on hosts.

Get Process

Get information about a running process.

POST /proc.ProcInterface/GetProc

Request Body:

{
  "id": "proc-id-ghi"
}

Response:

{
  "proc": {
    "id": "proc-id-ghi",
    "name": "render_process",
    "logPath": "/tmp/rqd/logs/render_process.log",
    "unbooked": false,
    "reserved": true,
    "bookedCores": 4,
    "virtualMemory": 8589934592,
    "usedMemory": 4294967296,
    "bookedGpus": 1,
    "usedGpuMemory": 2147483648
  }
}

Kill Process

Terminate a running process.

POST /proc.ProcInterface/Kill

Request Body:

{
  "proc": {
    "id": "proc-id-ghi"
  }
}

Unbook Process

Unbook resources from a process.

POST /proc.ProcInterface/Unbook

Request Body:

{
  "proc": {
    "id": "proc-id-ghi"
  }
}

---

Deed Interface

Manage resource deeds and ownership records.

Get Deed Owner

Get the owner of a deed.

POST /deed.DeedInterface/GetOwner

Request Body:

{
  "deed": {
    "id": "deed-id-jkl"
  }
}

Response:

{
  "owner": {
    "name": "artist1",
    "maxCores": 20,
    "minCores": 2
  }
}

Get Deed Host

Get the host associated with a deed.

POST /deed.DeedInterface/GetHost

Request Body:

{
  "deed": {
    "id": "deed-id-jkl"
  }
}

Response:

{
  "host": {
    "id": "host-id-abc",
    "name": "render-node-01",
    "lockState": "OPEN",
    "totalCores": 16,
    "idleCores": 8
  }
}

---

Data Types

Common Types

Job States

PENDING    - Job is waiting to start
RUNNING    - Job has active frames
FINISHED   - Job completed successfully
KILLED     - Job was terminated
PAUSED     - Job is paused

Frame States

WAITING    - Frame is waiting to start
RUNNING    - Frame is currently executing
SUCCEEDED  - Frame completed successfully
DEAD       - Frame failed
EATEN      - Frame was skipped

Host Lock States

OPEN       - Host accepts new jobs
LOCKED     - Host locked by user
NIMBY      - Host locked automatically

Request/Response Objects

Job Object

{
  "id": "string",
  "name": "string",
  "state": "JobState",
  "shot": "string",
  "show": "string",
  "user": "string",
  "group": "string",
  "facility": "string",
  "priority": "int32",
  "minCores": "float",
  "maxCores": "float",
  "isPaused": "bool",
  "hasComment": "bool",
  "startTime": "int32",
  "stopTime": "int32",
  "jobStats": {
    "runningFrames": "int32",
    "deadFrames": "int32",
    "pendingFrames": "int32",
    "succeededFrames": "int32",
    "totalFrames": "int32"
  }
}

Frame Object

{
  "id": "string",
  "name": "string",
  "layerName": "string",
  "number": "int32",
  "state": "FrameState",
  "retryCount": "int32",
  "exitStatus": "int32",
  "startTime": "int32",
  "stopTime": "int32",
  "maxRss": "string",
  "usedMemory": "string",
  "lastResource": "string",
  "totalCoreTime": "int32"
}

Host Object

{
  "id": "string",
  "name": "string",
  "lockState": "LockState",
  "bootTime": "int32",
  "pingTime": "int32",
  "os": "string",
  "totalCores": "int32",
  "idleCores": "int32",
  "totalMemory": "int64",
  "freeMemory": "int64",
  "totalGpus": "int32",
  "freeGpus": "int32"
}

---

Error Handling

Error Response Format

{
  "error": "string",
  "code": "int32",
  "message": "string"
}

Common Error Codes

Code	Status	Description
2	UNKNOWN	Unknown error occurred
3	INVALID_ARGUMENT	Invalid request parameters
5	NOT_FOUND	Requested resource not found
7	PERMISSION_DENIED	Insufficient permissions
16	UNAUTHENTICATED	Authentication required

HTTP Status Codes

Status	Meaning
200	Success
400	Bad Request - Invalid JSON or parameters
401	Unauthorized - Missing or invalid JWT
403	Forbidden - JWT validation failed
404	Not Found - Resource not found
500	Internal Server Error

---

Rate Limiting

The REST Gateway implements rate limiting to prevent abuse:

• Default Limit: 100 requests per second per client
• Configurable: Set via RATE_LIMIT_RPS environment variable
• Headers: Rate limit information in response headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1694001000

---

Best Practices

Performance

1. Batch Requests: Group related operations when possible
2. Use Pagination: Limit large data requests with page/limit parameters
3. Cache Responses: Implement client-side caching for static data
4. Connection Pooling: Reuse HTTP connections for multiple requests

Security

1. Token Expiration: Use short-lived JWT tokens (1-2 hours)
2. HTTPS Only: Always use HTTPS in production
3. Input Validation: Validate all request parameters
4. Error Handling: Don’t expose sensitive information in errors

Reliability

1. Retry Logic: Implement exponential backoff for failed requests
2. Circuit Breaker: Use circuit breaker pattern for service calls
3. Health Checks: Monitor gateway health endpoints
4. Graceful Degradation: Handle partial failures gracefully

---

SDK Examples

Python Client

import requests
import jwt
import time

class OpenCueClient:
    def __init__(self, base_url, jwt_secret):
        self.base_url = base_url
        self.jwt_secret = jwt_secret

    def _get_headers(self):
        token = jwt.encode({
            'sub': 'api-client',
            'exp': int(time.time()) + 3600
        }, self.jwt_secret, algorithm='HS256')

        return {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }

    def get_shows(self):
        response = requests.post(
            f'{self.base_url}/show.ShowInterface/GetShows',
            headers=self._get_headers(),
            json={}
        )
        return response.json()

    def pause_job(self, job_id):
        response = requests.post(
            f'{self.base_url}/job.JobInterface/Pause',
            headers=self._get_headers(),
            json={'job': {'id': job_id}}
        )
        return response.json()

# Usage
client = OpenCueClient('http://localhost:8448', 'your-secret')
shows = client.get_shows()
client.pause_job('job-id-123')

JavaScript Client

class OpenCueClient {
  constructor(baseUrl, jwtSecret) {
    this.baseUrl = baseUrl;
    this.jwtSecret = jwtSecret;
  }

  async getHeaders() {
    const token = await this.createJWT();
    return {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    };
  }

  async createJWT() {
    // Use jsonwebtoken library
    const jwt = require('jsonwebtoken');
    return jwt.sign({
      sub: 'web-client',
      exp: Math.floor(Date.now() / 1000) + 3600
    }, this.jwtSecret);
  }

  async getShows() {
    const headers = await this.getHeaders();
    const response = await fetch(
      `${this.baseUrl}/show.ShowInterface/GetShows`,
      {
        method: 'POST',
        headers,
        body: JSON.stringify({})
      }
    );
    return response.json();
  }

  async pauseJob(jobId) {
    const headers = await this.getHeaders();
    const response = await fetch(
      `${this.baseUrl}/job.JobInterface/Pause`,
      {
        method: 'POST',
        headers,
        body: JSON.stringify({ job: { id: jobId } })
      }
    );
    return response.json();
  }
}

// Usage
const client = new OpenCueClient('http://localhost:8448', 'your-secret');
const shows = await client.getShows();
await client.pauseJob('job-id-123');

---

What’s next?

• Using the REST API - Usage examples and integration
• REST API Tutorial - Step-by-step walkthrough
• Deploying REST Gateway - Deployment instructions
• CueWeb Developer Guide - Integration examples with CueWeb