PUT /api/definitions

Register or update a process definition

Requires the deploy permission (or admin).

Request

{
  "name": "order_pipeline",
  "tasks": [
    {
      "id": "charge",
      "action": {
        "type": "fetch",
        "url": "http://localhost:9001/charge",
        "method": "post",
        "result_schema": {
          "type": "object",
          "properties": {
            "charged": {
              "type": "boolean"
            }
          }
        },
        "timeout": {
          "for": "5s"
        }
      },
      "on_error": [
        {
          "retry": {
            "retries": 3
          }
        }
      ],
      "switch": [
        {
          "case": "self.output.charged == true",
          "goto": "$ship"
        },
        {
          "goto": "$refund"
        }
      ]
    },
    {
      "id": "ship",
      "action": {
        "type": "fetch",
        "url": "http://localhost:9002/ship",
        "method": "post",
        "timeout": {
          "for": "3s"
        }
      },
      "on_error": [
        {
          "retry": {
            "retries": 2
          }
        }
      ],
      "switch": [
        {
          "goto": "end"
        }
      ]
    },
    {
      "id": "refund",
      "action": {
        "type": "fetch",
        "url": "http://localhost:9003/refund",
        "method": "post",
        "timeout": {
          "for": "3s"
        }
      },
      "on_error": [
        {
          "retry": {
            "retries": 1
          }
        }
      ],
      "switch": [
        {
          "goto": "end"
        }
      ]
    }
  ],
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "integer"
      }
    },
    "required": [
      "order_id"
    ]
  }
}

Response

{
  "name": "order_pipeline",
  "saved": true,
  "version": 1
}

Fails with 400, 500.

GET /api/definitions

List all registered process definitions (newest registered first)

Requires the read permission (or admin).

Parameter	In	Description
created_after	query	Only versions registered at/after this unix-millis timestamp
created_before	query	Only versions registered strictly before this unix-millis timestamp
sort	query	Sort key (per-endpoint whitelist; omit for the default)
order	query	Sort direction (omit for the endpoint default). One of asc, desc.
limit	query	Page size (default 20, cap 100)
after	query	Cursor from a previous page’s page.next_cursor — fetch the next page
before	query	Cursor from a previous page’s page.previous_cursor — fetch the previous page

Response

{
  "items": null,
  "page": {
    "size": 0,
    "items_before": 0,
    "items_after": 0,
    "sort": "",
    "order": ""
  }
}

Fails with 400, 500.

PUT /api/definitions/batch

Apply process definitions to a channel, atomically

Requires the deploy permission (or admin).

Request

{
  "definitions": [
    {
      "name": "child_process",
      "tasks": [
        {
          "id": "run",
          "action": {
            "type": "fetch",
            "url": "http://localhost:9001/run",
            "method": "post"
          },
          "switch": []
        }
      ]
    }
  ],
  "channel": "latest"
}

Response

[
  {
    "name": "child_process",
    "version": 1,
    "saved": true,
    "previous": 0
  }
]

Fails with 400, 500.

POST /api/definitions/validate

Validate process definitions and return inferred JSON schemas (no save)

Requires the read permission (or admin).

Request

[
  {
    "name": "order_pipeline",
    "tasks": [
      {
        "id": "charge",
        "action": {
          "type": "fetch",
          "url": "http://localhost:9001/charge",
          "method": "post"
        },
        "switch": []
      }
    ]
  }
]

Response

[
  {
    "process": "order_pipeline",
    "version": 1
  }
]

Fails with 400, 500.

POST /api/definitions/compat

Compare two sets of process versions: could an instance running one continue under the other, and does the newer one still honour the output contract consumers were written against. It is a shape check — it cannot see a change of meaning such as dollars becoming cents

Requires the read permission (or admin).

Request

{
  "from": {
    "channel": "latest"
  },
  "to": {
    "versions": {
      "order_pipeline": 3
    }
  },
  "process": "order_pipeline"
}

Response

{
  "compatible": true,
  "passes": false,
  "processes": [
    {
      "name": "order_pipeline",
      "status": "compared",
      "from": 1,
      "to": 3,
      "upgrade": {
        "compatible": true
      },
      "contract": {
        "compatible": false
      },
      "changed": [
        {
          "address": "ship:fetch.url",
          "task": "ship"
        }
      ],
      "issues": [
        {
          "member": "contract",
          "address": "output",
          "path": "fee",
          "message": "number → string",
          "gating": true
        }
      ]
    }
  ]
}

Fails with 400, 404, 500.