Start an instance

POST /sop/:name/start

Creates a new instance of the named process and begins execution. Pass all required inputs in the JSON body. The engine validates inputs against the process schema and returns 422 if any required field is missing or fails validation.

AUTH —

Requires X-SOP-Token header. See Authentication.

Path parameters

name string REQUIRED: The process name. Must match an existing published process exactly.

Request body

Content-Type: application/json

inputs object REQUIRED: Key-value map of process inputs. All fields declared as required: true in the process definition must be present.

Response

201 application/json — New instance object with id and initial state.

Errors

404 not_found No published process with that name.

422 invalid_inputs One or more inputs failed schema validation.

401 unauthorized Token missing or revoked.

curl https://api.opensop.dev/sop/customer-onboarding/start \
  -X POST \
  -H "X-SOP-Token: $OPENSOP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"company_name":"Acme Corp","country":"US"}}'

const res = await fetch(
  "https://api.opensop.dev/sop/customer-onboarding/start",
  {
    method: "POST",
    headers: {
      "X-SOP-Token": process.env.OPENSOP_TOKEN,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      inputs: { company_name: "Acme Corp", country: "US" }
    })
  }
);
const instance = await res.json();

resp = requests.post(
  "https://api.opensop.dev/sop/customer-onboarding/start",
  json={
    "inputs": {
      "company_name": "Acme Corp",
      "country": "US"
    }
  },
  headers={"X-SOP-Token": os.environ["OPENSOP_TOKEN"]}
)
print(resp.json())

Net::HTTP.start("api.opensop.dev", use_ssl: true) do |h|
  req = Net::HTTP::Post.new("/sop/customer-onboarding/start")
  req["X-SOP-Token"]   = ENV["OPENSOP_TOKEN"]
  req["Content-Type"] = "application/json"
  req.body = { inputs: { company_name: "Acme Corp", country: "US" } }.to_json
  puts h.request(req).body
end

REQUEST BODY · application/json

{
  "inputs": {
    "company_name": "Acme Corp",
    "country":       "US"
  }
}

RESPONSE 201

{
  "id":         "01HXYZ_ACME_001",
  "process":    "customer-onboarding",
  "version":    "1.0",
  "state":      "running",
  "started_at": "2024-01-15T10:30:00Z"
}