Generate an OpRun#

After a developer has deployed an op to your gyoza cluster, it becomes an OpDefinition on the server. You can now instantiate an OpRun from it to actually execute the op with your inputs.

All interactions happen through the gyoza server REST API. This guide uses curl for the examples, but any HTTP client works the same way.

See also

Full API reference with all endpoints and schemas: REST API.

Prerequisites#

We will use http://localhost:5555 as the server URL, my-secret-token as the API key and classify-op as the OpDefinition name throughout this guide.

Check the input spec#

Before creating a run you need to know what inputs the op expects. You can fetch the OpDefinition by name using:

GET /definitions/{name}

For our classify-op example:

curl http://localhost:5555/definitions/classify-op \
  -H "X-API-Key: my-secret-token"

The response includes (among other fields) the input_specs section:

{
  "id": "classify-op",
  "version": "1.0.0",
  "input_specs": {
    "image_path": {"type": "string", "required": true},
    "top_k":      {"type": "int",    "required": false, "default": 3}
  }
}

This tells you that image_path is required (a string) and top_k is optional (defaults to 3). Your run request must satisfy these constraints.

Create the run#

To create an OpRun, send a POST to the definition’s runs endpoint:

POST /definitions/{name}/runs

For our classify-op example, providing the inputs that match the spec above:

curl -X POST http://localhost:5555/definitions/classify-op/runs \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-token" \
  -d '{
    "inputs": {
      "image_path": "/remote/path/photo.jpg",
      "top_k": 3
    },
    "priority": 5
  }'
inputs

The input payload for the op. Required fields must be present and types must match the input_specs, otherwise the server returns a 400 error.

priority

Optional. Scheduling priority for the execution of the op. OpRuns with higher priority are executed first by the scheduler.

If you need to run a specific version of the OpDefinition, you can append a version query parameter to the request, if you don’t specify a version, the server will use the latest version of the definition by default.

curl -X POST "http://localhost:5555/definitions/classify-op/runs?version=1.0.0" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-token" \
  -d '{"inputs": {"image_path": "/remote/path/photo.jpg"}}'

The response is the full OpRun object, including its id, save it, you will need it to monitor, cancel, or retry the run:

{
  "id": "a1b2c3d4-...",
  "state": "PENDING",
  "priority": 5,
  "progress": 0,
  "current_attempt": 1,
  "image": "myregistry/classify-op:1.0.0",
  "inputs": {"image_path": "/remote/path/photo.jpg", "top_k": 3},
  "outputs": {},
  "op_definition": "classify-op",
  "createdAt": "2026-03-02T20:00:00Z",
  "updatedAt": "2026-03-02T20:00:00Z"
}

The run starts in PENDING state and will be picked up by a worker automatically.

Next steps#