OGraf Server API - HTTP | Pixotope Help Center

The OGraf server exposes the OGraf server API over HTTP on port 16219. All endpoints below are served under the /ograf/v1 prefix and exchange JSON.

Errors are returned as RFC 7807 problem details with the matching HTTP status code:

{ "title": "Not Found", "status": 404, "detail": "Renderer renderer-1 not registered" }

Server

Server information for the OGraf HTTP API.

GET /ograf/v1/ [CALL]

GET /ograf/v1/

Returns basic information about the OGraf server. description, author and version are omitted when not set.

No params.

Result

name	string	Server name.
description optional	string	Server description.
author optional	object	Server author (name, and optionally email and url).
version optional	string	Server version.

Example - Get server info

Request (you send)

GET /ograf/v1/

Response (you receive)

JSON

{
  "name": "Pixotope OGraf Server",
  "version": "1.0.0"
}

Graphics

Graphics installed on the OGraf server.

GET /ograf/v1/graphics [CALL]

GET /ograf/v1/graphics

Lists all installed graphics.

No params.

Result

graphics

object[]

Installed graphics. Each entry has id, name and an optional description.

Example - List graphics

Request (you send)

GET /ograf/v1/graphics

Response (you receive)

JSON

{
  "graphics": [
    {
      "id": "lower-third",
      "name": "Lower Third"
    }
  ]
}

GET /ograf/v1/graphics/{graphicId} [CALL]

GET /ograf/v1/graphics/{graphicId}

Responds with 404 Not Found if the graphic is not installed.

Returns the OGraf manifest of an installed graphic together with its metadata.

Params

graphicId

string

Graphic ID (path parameter).

Result

graphic	object	The graphic's OGraf manifest, as defined by the OGraf specification.
metadata	object	createdAt, and optionally createdBy, updatedAt and updatedBy.

Example - Get a graphic

Request (you send)

GET /ograf/v1/graphics/lower-third

Response (you receive)

JSON

{
  "graphic": {
    "id": "lower-third",
    "name": "Lower Third"
  },
  "metadata": {
    "createdAt": "2026-01-01T10:00:00Z"
  }
}

DELETE /ograf/v1/graphics/{graphicId} [CALL]

DELETE /ograf/v1/graphics/{graphicId}

Deletes an installed graphic. Not implemented yet: the server responds with 501 Not Implemented.

Params

graphicId	string	Graphic ID (path parameter).
force optional (default: false)	boolean	Query parameter. Currently has no effect.

Example - Delete a graphic

Request (you send)

DELETE /ograf/v1/graphics/lower-third

Response (you receive)

JSON

{
  "title": "Not Implemented",
  "status": 501,
  "detail": "This endpoint is not yet implemented"
}

Renderers

Renderers registered with the OGraf server and the render targets they expose.

GET /ograf/v1/renderers [CALL]

GET /ograf/v1/renderers

Lists all registered renderers.

No params.

Result

renderers

object[]

Registered renderers. Each entry has id, name and an optional description.

Example - List renderers

Request (you send)

GET /ograf/v1/renderers

Response (you receive)

JSON

{
  "renderers": [
    {
      "id": "renderer-1",
      "name": "Renderer 1"
    }
  ]
}

GET /ograf/v1/renderers/{rendererId} [CALL]

GET /ograf/v1/renderers/{rendererId}

Responds with 404 Not Found if the renderer is not registered.

Returns information about a renderer and the render targets it exposes. To get the graphic instances loaded on a render target, use GET /ograf/v1/renderers/{rendererId}/target.

Params

rendererId

string

Renderer ID (path parameter).

Result

renderer

object

id, name, status and renderTargets, and optionally description, customActions, renderCharacteristics and renderTargetSchema.

Example - Get a renderer

Request (you send)

GET /ograf/v1/renderers/renderer-1

Response (you receive)

JSON

{
  "renderer": {
    "id": "renderer-1",
    "name": "Renderer 1",
    "status": {
      "status": "OK"
    },
    "renderTargets": [
      {
        "renderTarget": {
          "layer": 1
        },
        "name": "Layer 1"
      }
    ]
  }
}

GET /ograf/v1/renderers/{rendererId}/target [CALL]

GET /ograf/v1/renderers/{rendererId}/target

Responds with 400 Bad Request if renderTarget is not valid JSON, and 404 Not Found if the renderer is not registered.

Returns a render target and the graphic instances currently loaded on it.

Params

rendererId	string	Renderer ID (path parameter).
renderTarget	string	Query parameter. JSON-encoded, URL-encoded render target identifier, e.g. {"layer":1}.

Result

renderTarget	object	The render target identifier.
name	string	Render target name.
graphicInstances	object[]	Loaded graphic instances (graphicInstanceId and graphic).

Example - Get a render target

Request (you send)

GET /ograf/v1/renderers/renderer-1/target?renderTarget=%7B%22layer%22%3A1%7D

Response (you receive)

JSON

{
  "renderTarget": {
    "layer": 1
  },
  "name": "Layer 1",
  "graphicInstances": [
    {
      "graphicInstanceId": "a1b2c3d4",
      "graphic": {
        "id": "lower-third",
        "name": "Lower Third"
      }
    }
  ]
}

POST /ograf/v1/renderers/{rendererId}/customActions/{customActionId} [CALL]

POST /ograf/v1/renderers/{rendererId}/customActions/{customActionId}

Invokes a custom action declared by the renderer.

Params

rendererId	string	Renderer ID (path parameter).
customActionId	string	Custom action ID (path parameter).
payload	any	Action payload, as defined by the custom action.
skipAnimation optional	boolean	Skip any animation the action would trigger.

Result

result optional

any

Result returned by the renderer, if any.

Example - Invoke a renderer custom action

Request (you send)

POST /ograf/v1/renderers/renderer-1/customActions/reset

JSON

{
  "payload": {},
  "skipAnimation": true
}

Response (you receive)

JSON

{
  "result": null
}

Graphic Instances

Actions on graphic instances loaded on a renderer's render targets. Every request includes the renderTarget it applies to, for example {"layer":1}.

PUT /ograf/v1/renderers/{rendererId}/target/graphicInstance/clear [CALL]

PUT /ograf/v1/renderers/{rendererId}/target/graphicInstance/clear

Clears the graphic instances matching any of the given filters. The request does not wait for the renderer to finish, so the response always contains an empty graphicInstances list.

Params

rendererId	string	Renderer ID (path parameter).
filters	object[]	Filters selecting what to clear. Each filter may set renderTarget, graphicId and graphicInstanceId.

Result

graphicInstances

object[]

Always an empty list.

Example - Clear a layer

Request (you send)

PUT /ograf/v1/renderers/renderer-1/target/graphicInstance/clear

JSON

{
  "filters": [
    {
      "renderTarget": {
        "layer": 1
      }
    }
  ]
}

Response (you receive)

JSON

{
  "graphicInstances": []
}

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/load [CALL]

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/load

Responds with 404 Not Found if the renderer is not registered.

Loads a graphic onto a render target.

Params

rendererId	string	Renderer ID (path parameter).
renderTarget	object	Render target to load onto.
graphicId	string	ID of the installed graphic to load.
params	object	Load parameters. params.data holds the initial graphic data.
graphicInstanceId optional	string	Pixotope extension. ID to assign to the loaded graphic instance.

Result

graphicInstanceId	string	ID of the loaded graphic instance.
statusCode	number	Status code reported by the renderer.
statusMessage optional	string	Status message reported by the renderer.

Example - Load a graphic

Request (you send)

POST /ograf/v1/renderers/renderer-1/target/graphicInstance/load

JSON

{
  "renderTarget": {
    "layer": 1
  },
  "graphicId": "lower-third",
  "params": {
    "data": {
      "title": "Hello"
    }
  }
}

Response (you receive)

JSON

{
  "graphicInstanceId": "a1b2c3d4",
  "statusCode": 200
}

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/updateAction [CALL]

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/updateAction

Updates the data of a loaded graphic.

Params

rendererId	string	Renderer ID (path parameter).
renderTarget	object	Render target the graphic is loaded on.
graphicInstanceId	string	ID of the graphic instance.
params	object	params.data holds the new graphic data, params.skipAnimation optionally skips animation.

Result

graphicInstanceId	string	ID of the graphic instance.
statusCode	number	Status code reported by the renderer.
statusMessage optional	string	Status message reported by the renderer.

Example - Update a graphic

Request (you send)

POST /ograf/v1/renderers/renderer-1/target/graphicInstance/updateAction

JSON

{
  "renderTarget": {
    "layer": 1
  },
  "graphicInstanceId": "a1b2c3d4",
  "params": {
    "data": {
      "title": "Updated"
    }
  }
}

Response (you receive)

JSON

{
  "graphicInstanceId": "a1b2c3d4",
  "statusCode": 200
}

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/playAction [CALL]

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/playAction

Plays a loaded graphic, either advancing it by delta steps or jumping to step goto.

Params

rendererId	string	Renderer ID (path parameter).
renderTarget	object	Render target the graphic is loaded on.
graphicInstanceId	string	ID of the graphic instance.
params	object	params.delta steps to advance by, params.goto step to jump to, and params.skipAnimation. All optional.

Result

graphicInstanceId	string	ID of the graphic instance.
statusCode	number	Status code reported by the renderer.
statusMessage optional	string	Status message reported by the renderer.
currentStep	number	Step the graphic is expected to be on after the action.

Example - Play a graphic

Request (you send)

POST /ograf/v1/renderers/renderer-1/target/graphicInstance/playAction

JSON

{
  "renderTarget": {
    "layer": 1
  },
  "graphicInstanceId": "a1b2c3d4",
  "params": {
    "delta": 1
  }
}

Response (you receive)

JSON

{
  "graphicInstanceId": "a1b2c3d4",
  "statusCode": 200,
  "currentStep": 1
}

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/stopAction [CALL]

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/stopAction

Stops a loaded graphic.

Params

rendererId	string	Renderer ID (path parameter).
renderTarget	object	Render target the graphic is loaded on.
graphicInstanceId	string	ID of the graphic instance.
params	object	params.skipAnimation optionally skips animation. Pass an empty object otherwise.

Result

graphicInstanceId	string	ID of the graphic instance.
statusCode	number	Status code reported by the renderer.
statusMessage optional	string	Status message reported by the renderer.

Example - Stop a graphic

Request (you send)

POST /ograf/v1/renderers/renderer-1/target/graphicInstance/stopAction

JSON

{
  "renderTarget": {
    "layer": 1
  },
  "graphicInstanceId": "a1b2c3d4",
  "params": {}
}

Response (you receive)

JSON

{
  "graphicInstanceId": "a1b2c3d4",
  "statusCode": 200
}

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/customActions/{customActionId} [CALL]

POST /ograf/v1/renderers/{rendererId}/target/graphicInstance/customActions/{customActionId}

Invokes a custom action declared by a loaded graphic.

Params

rendererId	string	Renderer ID (path parameter).
customActionId	string	Custom action ID (path parameter).
renderTarget	object	Render target the graphic is loaded on.
graphicInstanceId	string	ID of the graphic instance.
params	object	params.payload holds the action payload, params.skipAnimation optionally skips animation.

Result

graphicInstanceId	string	ID of the graphic instance.
statusCode	number	Status code reported by the renderer.
statusMessage optional	string	Status message reported by the renderer.

Example - Invoke a graphic custom action

Request (you send)

POST /ograf/v1/renderers/renderer-1/target/graphicInstance/customActions/highlight

JSON

{
  "renderTarget": {
    "layer": 1
  },
  "graphicInstanceId": "a1b2c3d4",
  "params": {
    "payload": {
      "color": "red"
    }
  }
}

Response (you receive)

JSON

{
  "graphicInstanceId": "a1b2c3d4",
  "statusCode": 200
}