# Run Orange Wire on a BRD

`wire.run`

Finds the pack that answers the BRD, by its digest first and by pack second, and starts a run that the sweep carries out: compose saves the pack's HSX as a new sandbox Core, then records writes every lifecycle record of the pack as the member who holds each role's staff role and reaches every Product, else as you, with the Product's sandbox clock moved to each record's day, then tests waits for the Core's checks to settle and writes the pack's first SIT cycle with one run result per test case: a case that names a check takes pass or fail from that check's stored result and its failure text, and a case run by hand keeps the pack's result. The pack's last record falls on today, or its days count from day0 when you name one; a day0 that would date a record after today refuses invalid_request. Read the run with wire.run.retrieve. A BRD no pack answers refuses wire_pack_missing, and a pack whose test case names a check its program does not declare refuses wire_pack_check_unknown before anything is written. A second run on the same pack in the company returns the first run and plays it again on the same Product, which writes nothing already written. No gate is submitted.

Callers: the account owner's CLI login, or an agent token with blueprints:write, or a personal access token with blueprints:write.

`POST /v1/wire/runs`

Principal `user_session`. Idempotency `required`. Environment `sandbox`.

## Input

| Field | In | Type | Description |
| --- | --- | --- | --- |
| `X-Hyperscale-Environment` | header | `sandbox \| live` |  |
| `Idempotency-Key` required | header | `string` |  |
| `X-Hyperscale-Rehearsal` | header | `"true"` | `true` runs the request through admission and execution, keeps nothing, and answers OperationRehearsal with 200 in place of the operation's own output. Needs a signed-in caller. Identity operations, such as sign-in, sessions, team members and agent grants, refuse it with invalid_request. |
| `tenantId` required | body | `string` | Organization tenant ID |
| `brdText` required | body | `string` | The business requirements document, as the analyst pastes it |
| `pack` | body | `string` | The pack to play when no pack answers this BRD's digest, such as one wire.pack.list offers |
| `name` | body | `string` | The Core's name; the pack's title when left out |
| `day0` | body | `string` | The day the pack's days count from. Left out, the pack's last record falls on today; named, it must not put any record after today |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `runId` required | `string` | Wire run ID, such as wrn_sandbox_... |
| `tenantId` required | `string` | Organization tenant ID |
| `packKey` required | `string` | A pack's key: its file name in the packs directory, without .json |
| `brdDigest` required | `string` | SHA-256 of the BRD after whitespace normalisation: trimmed, every run of whitespace one space |
| `productId` required | `string \| null` | The Core's Product, once compose has run; null before |
| `requestedBy` required | `string` | The user id of the analyst who ran it |
| `status` required | `pending \| running \| done \| failed` |  |
| `steps` required | `object[]` | compose, records and tests, in order. compose counts the Product it made or found; records counts lifecycle records; tests counts the first SIT cycle, its run results and the records that hang on that cycle. tests stays pending while the Core's checks run |
| `attempts` required | `integer` | How many times the sweep has taken the run's current step; it starts again at each step and each rerun, and a sweep that finds the Core's checks still running does not count |
| `refusal` required | `object \| null` | Why a failed run stopped: wire_run_failed with the refusal the step met in details.cause, such as a compile refusal and its diagnostics, or when the Core's checks never settled; wire_pack_invalid when the pack cannot be written; wire_pack_check_unknown when a test case names a check the Core's results lack |
| `createdAt` required | `string` |  |
| `updatedAt` required | `string` |  |
| `finishedAt` required | `string \| null` |  |

## Request sample

Only a signed-in person may call this: the CLI after hyperscale auth login, or curl with a personal access token (hyperscale_pat_...) with blueprints:write or an agent token with blueprints:write. The agent's grant must span every Product the call reads. A Product key cannot, so the SDK, which signs in with a Product key or a customer session, has no sample for it.

### curl

```shell
curl --request POST 'https://hyperscale0.ai/v1/wire/runs' \
  --header "Authorization: Bearer $HYPERSCALE_TOKEN" \
  --header 'X-Hyperscale-Environment: sandbox' \
  --header "Idempotency-Key: $(uuidgen)" \
  --header 'Content-Type: application/json' \
  --data-raw '{"tenantId":"ten_sandbox_example0001","brdText":"x"}'
```

### CLI

```shell
hyperscale api call wire.run \
  --input '{"tenantId":"ten_sandbox_example0001","brdText":"x"}'
```

## Errors

| Code | HTTP | Cause |
| --- | --- | --- |
| `agent_reason_required` | 400 | An agent sent a change without saying why, or the reason is shorter than 8 or longer than 280 characters. |
| `agent_result_already_delivered` | 409 | A caller already claimed this approval's one-time result. |
| `approval_rejected` | 403 | A person rejected the call or returned it to the maker, so it never runs. |
| `approval_required` | 202 | The call waits for decisions: an agent's call over its grant waits on its delegator, and a program action under `requires approval` waits on distinct people other than the maker. |
| `csrf_token_invalid` | 403 | A browser session mutation did not carry a current Hyperscale CSRF token. |
| `environment_mismatch` | 403 | The session was issued for sandbox or live and the request targets the other environment. |
| `idempotency_conflict` | 409 | The request reused an Idempotency-Key for a different logical mutation. |
| `idempotency_required` | 400 | The operation is a mutation and Hyperscale requires a replay key before executing it. |
| `internal_error` | 500 | Hyperscale hit an unexpected server-side condition and hid internal implementation details from this audience. |
| `invalid_request` | 400 | The request does not match the API reference. |
| `method_not_allowed` | 405 | The route exists, but not for the request's HTTP method. |
| `missing_required_permission` | 403 | The signed-in member's current role does not grant the permission required for this operation. |
| `missing_required_scope` | 403 | The credential is valid but does not grant one or more operation scopes. |
| `not_found` | 404 | No Hyperscale route matched the requested path and method. |
| `oauth_client_not_admitted` | 403 | The bearer is an OAuth client token, and this operation does not admit the oauth2_client principal. |
| `rate_limited` | 429 | The credential sent more than its limit in the current 60-second window: 600 requests per API key or session, 1,200 per IP address. Every response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (Unix seconds). |
| `request_body_too_large` | 413 | The JSON request body exceeded Hyperscale's accepted payload size. |
| `resource_not_found` | 404 | The requested resource does not exist in the credential's visible scope. |
| `state_conflict` | 409 | The operation conflicts with the current durable state of the resource. |
| `state_constraint_failed` | 422 | The request is syntactically valid but violates a business-state constraint. |
| `tenant_mismatch` | 403 | The request mixed tenant-owned identifiers across tenant boundaries. |
| `tenant_not_found` | 404 | The credential resolved to a tenant Hyperscale cannot find. |
| `unauthorized` | 403 | The request did not include a valid Hyperscale bearer credential for this environment. |
| `agent_token_expired` | 401 | The agent token is real, but its grant ended. A grant lasts 30 days, or 7 days unused. `details.expiresAt` holds the date in ISO 8601 and `details.agentName` names the agent. |
| `agent_token_replaced` | 401 | The account owner ran `hyperscale agent setup` again for this agent, which replaced this token with a newer one. `details.agentName` names the agent and `details.replacedAt` holds the date. |
| `device_login_expired` | 401 | The bearer is the account owner's own device login from `hyperscale auth login`, not an agent token. Its access token lasts an hour and the CLI refreshes it; the login itself ends after 30 days, or 7 days unused. `details.expiresAt` holds when it ended in ISO 8601. |
| `instrument_instance_not_found` | 404 | No record of this instrument matches the `instanceId` in this Product, company and environment. `details.instrumentId` and `details.instrumentInstanceId` name what was looked up. |
| `invalid_credentials` | 401 | Hyperscale could not accept the account or credential request. Signup, login, and bearer authentication use one 401 for every case they reject, so the response exposes no credential-specific reason or registered-email verdict. The single exception is a key that is real but homed in the other environment: because the presented secret already matched a stored key, the message names the mismatch instead of leaving a working credential looking unknown. A bearer that matched nothing gets text that fits its prefix (an agent token, a refresh token, a personal access token, a session or no Hyperscale token at all), which says only what the caller sent, never whether a credential like it exists. |
| `operation_not_finalized` | 409 | The operation in `details.operationId` has started but has no final receipt. It is still running, or its outcome is unknown after a failure past the point where it may have committed. `details.error` carries the underlying failure when there is one. |
| `session_expired` | 401 | The session behind this request has ended. A console session ends 30 days after sign-in, or after 12 hours with no request. An admin or customer session ends 24 hours after sign-in, or after 15 minutes with no request. A personal access token ends at the `expiresAt` set when it was created. |
| `session_required` | 401 | This operation needs a person signed in through the browser or the `hyperscale` CLI. A Product API key cannot call it. The request carried no session, or its token matched no live session. |
| `session_revoked` | 401 | The session or personal access token behind this request was ended before its expiry. Sign-out, `user.session.revoke`, a password reset, a role change, removal from the team, user suspension and `personal_access_token.revoke` all end sessions. |
| `tenant_status_forbidden` | 409 | The company is suspended or closed, so every credential bound to it is refused, reads included. `details.tenantId` names the company. |
| `wire_pack_check_unknown` | 422 | A test case in the pack names a check the pack's HSX program does not declare, so the run could not take its result from the Core's checks. details.cases lists each case and the check it names. |
| `wire_pack_missing` | 404 | No pack this Arc loaded answers the BRD's digest, and the request named no pack, or named one that is not loaded. |

[All operations](/docs/operations/index.md)

For agents: [OpenAPI document](https://hyperscale0.ai/openapi.json) · [MCP manifest](https://hyperscale0.ai/.well-known/mcp.json) · [HTTP API guide](https://hyperscale0.ai/docs/api.md) · [MCP guide](https://hyperscale0.ai/docs/mcp.md)