## `POST /sop/:name/start`

**Start an instance** — 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](/api-docs/guides/authentication.md).

### Path parameters

- `name` (string, required) — The process name. Must match an existing published process exactly.

### Request body

**Content-Type:** `application/json`

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

- `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`.

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

### Errors

| Status | Code | Meaning |
|--------|------|---------|
| 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. |

### Code examples

#### curl

```bash
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"}}'
```

#### Node

```js
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();
```

#### Python

```python
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())
```

#### Ruby

```ruby
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
```