Submit an inbound BYOA agent-dispatch request.
Authentication accepts an rsk API key, a requester-registration-bound OAuth agent token, a WorkOS user token, or a browser session. REG-10 is conditional: a bound registration with a public key requires all three X-Rensei-Request-* headers; a light registration without a key, an unbound rsk key, a user token, and a session do not. A strict registration without a key is misconfigured and returns 403. The public key is canonical standard base64 of the raw 32-byte Ed25519 key. The signature is canonical standard base64 of 64 bytes over the exact UTF-8 canonical-envelope JSON. Nonce replay rejection is best-effort: if Redis is unavailable, replay-cache checks fail open while signature and inclusive +/-300-second timestamp validation remain enforced. Typed requests evaluate only the current immutable configured HarnessConnection revision, an explicit live project grant, and current immutable production-promoted probe evidence; host inventory is never admission authority. A typed request that satisfies declared compatibility AND live inventory allocates a durable ledger session and returns an admitted response; anything short of that still returns a denial receipt. Spawn remains gated: an admitted node stays queued until an applied-adaptation receipt exists.
AuthorizationBearer <rsk_live_*>Rensei API key presented as Authorization: Bearer rsk_live_. Required API-key scopes are recorded per operation in x-rensei-required-scopes.
X-Rensei-Request-Signature?stringConditionally required: standard base64 of the 64-byte Ed25519 signature over the exact canonical envelope UTF-8 bytes.
^[A-Za-z0-9+/]{86}==$X-Rensei-Request-Timestamp?stringConditionally required: canonical base-10 integer Unix seconds signed in the envelope; accepted within the inclusive +/-300 second window.
^(0|[1-9][0-9]*)$X-Rensei-Request-Nonce?stringConditionally required: non-empty opaque per-request nonce signed in the envelope. Replay rejection is best-effort while the Redis replay cache is available.
1 <= lengthapplication/json- body
project*stringProject slug or id (must belong to the authenticated org).
1 <= lengthgoal*stringThe work the dispatched agent should accomplish.
1 <= lengthcard?stringDispatch card: slug, display name, or agent:// reference. Resolved with the dispatch card resolver against the cards the project can dispatch.
1 <= lengthworkType?stringDeprecated: legacy three-value work type (research, implement, review). Prefer card. When both are present, card wins; when only workType is present it maps to the matching system dispatch card.
targetRef?stringExisting remote branch to amend. Omitted preserves the default-branch plus fresh-work-branch flow.
1 <= length <= 255continuePullRequest?Open pull request to continue: { number }. At admission the PR must be open, belong to the dispatch project's repository, and have its head in that repository (no forks); otherwise the dispatch is refused with a typed CONTINUE_PR_* code. The resolved head ref and head SHA ride the session spec handed to the runner.
reviewTarget?Structured review target beside continuePullRequest: { repo, prNumber, headSha }. The repo is the repository full name (owner/repo), prNumber the pull request to review, headSha the resolved 40-hex head SHA the seat must review. When continuePullRequest names the same dispatch, the PR numbers (and head SHAs) must agree or the dispatch is refused with REVIEW_TARGET_PR_MISMATCH. The target rides the trigger and the session dispatch facts; the outcome writer stamps outcomes against it.
callbackUrl?|Optional HTTPS target for the current best-effort result push-back. Strict posture skips outbound delivery. A one-time callbackSecret is returned when non-null.
^https:uripool?stringStatic pool pin for this dispatch: a capacity pool id or display name. Overrides the project capacity profile for this dispatch; resolved through the same placement path the workflow agent.invoke node pin uses. Unknown or ambiguous names refuse; an unavailable pool falls back to the profile unless pinStrict is set.
1 <= lengthpinStrict?booleanFail-closed strictness for the pool pin. When true, an unavailable or offline pinned pool abandons the dispatch instead of falling back to the project profile. Default false. Requires pool.
issue?stringProvider-native issue reference. Required for a headless Pi A2A worker.
1 <= lengthlaunchSelection?Canonical D2.6 stage-0 launch intent. Use executionSelection.harness for revision-pinned headless harness selection.
params?Optional per-dispatch parameters: keys are the Agent Dispatch workflow's declared caller-settable parameters, plus cardInputs. Each key is validated with the Agent Dispatch call validator; a refused key returns 422 with a per-key code (DISPATCH_PARAM_UNKNOWN, DISPATCH_PARAM_NOT_CALLER_SETTABLE, DISPATCH_PARAM_INVALID_TYPE, DISPATCH_PARAM_WEAKENS_LIMIT, DISPATCH_PARAM_TOO_LARGE). cardInputs is then checked against the admitted card version's declared inputs (declared names only, declared types, required inputs present, declared defaults applied); a refused input returns 422 naming it (DISPATCH_CARD_INPUT_UNKNOWN, DISPATCH_CARD_INPUT_REQUIRED, DISPATCH_CARD_INPUT_INVALID_TYPE). Accepted values are validated and echoed back in the response; runtime composition is a separate unit. Omitted behaves exactly as before.
force?booleanDeliberate re-dispatch: bypass the per-issue in-flight refusal (ISSUE_ALREADY_IN_FLIGHT) when the issue already has a live session or an open pull request for the same work type. Omitted or false keeps the dedupe.
Legacy dispatch accepted, or a typed request resolved through the canonical session-ledger contract after database-backed authority evaluation. A configured connection that is granted to the project and carries a promoted probe at the required evidence tier allocates an admitted typed session; anything short of that is denied.
application/json- response
workflowId*stringinstanceId*stringsessionId*stringstreamUrl*stringreceiptUrl*stringrequestedProjectId*stringresolvedProjectId*stringrequestedHarness*string|nullexpectedA2AHandle*string|nullresolvedExecution*|Resolved execution at admission, using the runtime profile resolver. Null when admission-time resolution failed (transient resolver failure with no strong pin to refuse): the dispatch still proceeds and the runtime revalidates before execution; placement is decided at claim time.
modelSelection*The model profile this dispatch is pinned to and the assignment tier that pin matched. Best-effort attribution, not an execution guarantee: a cascade tier (project-byWorkType, org-default, …) means the cascade would have chosen the same profile, "override" means the caller pinned one it would not have, and "unattributed" means the cascade could not be resolved so the pin is reported with no tier. For a dispatch that pins nothing this is the cascade's answer AT ADMISSION TIME — the runtime re-resolves at execution — and modelProfileId is null when the cascade resolved none.
workflowAdmission*params?The accepted per-dispatch parameters, echoed back; cardInputs carries the admitted card's declared defaults for omitted inputs. Present only when the request carried params. Runtime composition is a separate unit — these values are validated, not yet applied.
resolvedParams?Per-parameter scope attribution: for each resolved Agent Dispatch parameter, the value and the tier that supplied it — caller (the request params), workflow (the project's stored value for the workflow parameter), default (the fired workflow's literal default), project or org (a default that is a $ref to that tier's resource); system is reserved. Secret-typed parameters (callbackUrl) report scope only, never a value. The same map rides the dispatch receipt. Present when the dispatch resolved at least one parameter: always for request params, and for a workflow that declares parameters even without them.
callbackSecret?stringReturned once when callbackUrl is non-null. Verify the current X-Rensei-Signature HMAC over the exact callback body with this secret.
^[0-9a-f]{64}$continuePullRequest?The continued pull request, echoed when the dispatch named one: number, resolved head ref and head SHA. The same spec rides the session spec handed to the runner.
reviewTarget?The structured review target, echoed when the dispatch named one: repo, PR number and head SHA. The same spec rides the trigger and the session dispatch facts.
warnings?array<>Present when the requested branch pin was accepted but is not yet honored by fleet runners — the work starts from the default branch. The warning will disappear once runner ref support ships; see also receipt baseRef and warnings.
promptTruncation?Present when the requester goal was capped for the seat starting prompt: the truncated sections with their before (originalChars) and after (keptChars) sizes. The seat prompt middle-truncates (head and tail survive). In a seat brief, the SEAT BRIEF ADDENDUM (a line opening with that phrase, as a heading or a list item, up to a Common rules heading) is kept ahead of the rest of the brief: whole when it fits the 6,000-character cap, otherwise its head plus every B finding line. The same map rides the dispatch receipt once the stage runs, with the seat-brief, description and acceptance-criteria entries the stage adds.
curl -X POST 'https://app.rensei.ai/api/cli/dispatch' \ -H 'Content-Type: application/json' \ -d '{ "project": "string", "goal": "string"}'{ "workflowId": "string", "instanceId": "string", "sessionId": "string", "streamUrl": "string", "receiptUrl": "string", "requestedProjectId": "string", "resolvedProjectId": "string", "requestedHarness": "string", "expectedA2AHandle": "string", "resolvedExecution": { "harness": "string", "provider": "string", "model": "string", "authMode": "byok", "modelProfileId": "string" }, "modelSelection": { "modelProfileId": "string", "source": "workflow-node-inline" }, "workflowAdmission": { "contractVersion": "rensei.workflow-admission/v1", "admissionId": "string", "lane": "agent_invoke", "workflowId": "string", "projectId": "string", "workflowRevision": "string", "definitionVersion": "string", "triggerId": "string", "authorizingNodeId": "string", "triggerBinding": "explicit", "launchSelectionBinding": "trigger.data.launchSelection" }, "params": { "property1": null, "property2": null }, "resolvedParams": { "property1": { "value": null, "scope": "system" }, "property2": { "value": null, "scope": "system" } }, "callbackSecret": "string", "continuePullRequest": { "number": 1, "headRef": "string", "headSha": "string" }, "reviewTarget": { "repo": "string", "prNumber": 1, "headSha": "string" }, "warnings": [ { "code": "refIgnored", "message": "string" } ], "promptTruncation": { "goal": { "originalChars": 0, "keptChars": 0 }, "description": { "originalChars": 0, "keptChars": 0 }, "seatBrief": { "originalChars": 0, "keptChars": 0 }, "acceptanceCriteria": { "originalChars": 0, "keptChars": 0 } }}List the organizations (workspaces) the authenticated principal belongs to.
List the organizations (workspaces) the authenticated principal belongs to. - Rensei REST API operation reference.
Get the assembled audit receipt for an inbound dispatch.
Returns the assembled receipt for one dispatched run: what it cost, which models it used, how it was decided - and, once the run is terminal, the child's own answer (`summary`) plus a typed `exitReason` (passed | failed | blocked | timeout | cancelled | unknown). `workType` names the session work type and its registry role (null for an unknown or retired name); null when no work type was recorded. `reasoningEffort` reports the effort the run executed at, as its runner reported it. `capabilitiesNotDelivered` lists the non-essential capability demands the resolved harness profile could not deliver, so the session ran without them. `resolvedParams` reports, for each resolved Agent Dispatch parameter, the value and the scope that supplied it (system | org | project | workflow | caller | default); secret-typed parameters (`callbackUrl`) report scope only, never a value. `result` carries the run's typed outcome as its runner reported it: the review `verdict` (APPROVE | APPROVE_WITH_FOLLOWUPS | REQUEST_CHANGES as delivered, or FAILED for a review that ended failed, blocked or timed out without delivering one; review work only), the run's `pullRequest` ({ number, url, headSha }, also on failed and blocked runs; for review work it is the PR the reviewer reported, usually the one under review and unverified by the runner, with the review session's own head) and `ciState`; `reviewedHeadSha`, when present, is the PR head pinned in the dispatch review target, independent of the workarea head. `reviewedPullRequest`, when present, names that pinned target ({ repo, number, url }), independently of the runner-reported PR; absent when the target repository is invalid. A null member means the runner never reported it. `promptTruncation` reports, for each capped starting-prompt section, the before (originalChars) and after (keptChars) sizes. `terminalReason` carries the structured failure reason (`code`, `message`, `phase`, `decidedBy`, `at`) for a terminal `failed` session, as stamped by the writer that ended it; null when the run ended any other way or predates the stamp. `pendingAdmission` reports the last observed reason, rule, attempts and observedAt while the session is pending; null otherwise. An old observedAt means no recent admission observation, not a fresh host diagnosis. `inferences[].reasoningTokens` carries the reported reasoning count (an output subset, never priced twice; null means not reported). The Ed25519 signature is over `decision.entryHash` and is unaffected by these fields; `receiptIntegrity.receiptVersion` names the sealed field set: newly assembled receipts are 'v11' (adds `executionSelection.placementSource/placementPoolId/placementFallbackFrom` and, on review-target receipts, `result.reviewedHeadSha` and the pinned `result.reviewedPullRequest` when its repository is valid), 'v12' is an accepted spelling for the v10 body plus inference `reasoningTokens` (never sealed), and archived ones stay valid as 'v10' (adds `capabilitiesNotDelivered`), 'v9' (adds `terminalReason`), 'v8' (adds `promptTruncation`), 'v7' (adds `result`), 'v6' (adds `resolvedParams`), 'v5' (adds `continuedPullRequest`), 'v4' (adds `budgetBreach`), 'v3' (adds `reasoningEffort`), 'v2' (adds the answer fields) or 'v1' (the original body).