HTTP Actions

HTTP Action is the smallest runtime integration for one consequential Agent action. The Agent sends one ordinary HTTP request to the customer-owned Witnora Gateway. That request becomes an Action held for the normal approval, execution, independent Probe, and Receipt path.

The current implementation covers one exact sandbox Task/action path. It does not create a production Provider connection, add permissions, or raise the evidence level by itself.

Before you start

In Hosted Onboarding, choose HTTP Action, copy the displayed command, and run it in the Agent repository:

npx witnora@latest onboard --project <project-id> --action-transport http
npx witnora@latest gateway doctor

The CLI checks the exact local Gateway binding and action-scoped credential, then posts a restricted transport-test receipt to Hosted. Onboarding refreshes that state automatically and shows the copyable endpoint only after the repository-side check arrives. Verification does not execute an Action.

Onboarding creates these local files when exactly one sandbox Action path is active:

• .witnora/gateway/HTTP_ACTION.md — the copyable endpoint and request shape;
• .witnora/gateway/http-action.json — the exact Task/action binding;
• .witnora/gateway/data/http-actions/<action-id>.token — an ignored, action-scoped token.

The action token is not the full Gateway credential. Put it in the calling Agent platform's secret store and never print it in CI logs or commit it.

If setup says it is waiting for an Action path, base Gateway setup succeeded but HTTP Action is not connected yet. Keep the original command open and do not edit generated files. Complete the customer flow in this order:

1. In a second terminal, run the exact Agent command shown in Hosted (or run the Agent's normal sandbox workflow).
2. Confirm the automatically prepared Business Task and its suggested capabilities. One observed capability may have multiple classifications.
3. Keep the original terminal open while it detects the Task and verifies the exact Action path automatically.
4. If the selected Probe needs a Provider credential, put its read-only sandbox credential in the local Agent environment.
5. If the original terminal was closed, use the collapsed recovery command in Hosted. This is recovery, not a normal second onboarding step.

For a Stripe refund Probe, prefer the least-privilege restricted test key:

$env:STRIPE_RESTRICTED_TEST_KEY = "rk_test_..."
npx witnora@latest onboard --project <project-id> --action-transport http
Remove-Item Env:STRIPE_RESTRICTED_TEST_KEY

STRIPE_SECRET_KEY=sk_test_... remains a backward-compatible fallback. Do not use a live key or put either credential in the repository. Base onboarding remains intact and the transport test stays visibly incomplete until the repository-side receipt arrives.

Send one Action

The generated guide contains the exact endpoint. A typical request looks like:

POST http://127.0.0.1:8787/v1/http-actions/cancel-order
Authorization: Bearer <action-scoped token>
Idempotency-Key: cancel-order-42-v1
Content-Type: application/json

{
  "resourceId": "order-42",
  "status": "CANCELLED"
}

Only resourceId and status are accepted. The idempotency key is required, must be stable for an exact retry, and must not be reused for a changed body. Unsupported fields fail closed instead of being forwarded.

What happens next

The first successful response normally contains an Action in PENDING_APPROVAL. That means the request was recorded and held. It does not mean the business result happened.

1. A human reviews the exact Action in the Witnora workspace.
2. Approval binds that exact resource and requested state.
3. The customer-owned Runtime performs at most one authorized sandbox write.
4. A separate read-only Probe observes the target state.
5. Witnora preserves the approval, execution, observation, and limitations in a signed Receipt.

Use Agents → Actions to inspect the Action's reported and independently verified states. A final VERIFIED state with a signed Receipt is scoped to that Action only; it is not a claim that the whole Agent is safe.

Verify retry behavior

Send the exact same request again with the same Idempotency-Key. Witnora returns the same logical Action and the Runtime does not create another authorized write.

If the body changes while the key stays the same, the Gateway returns HTTP 409 with an idempotency conflict. Use a new key only for a genuinely new business action.

Connect a cloud Agent

The generated endpoint listens inside the customer environment. A cloud-hosted Agent must reach it through the customer's authenticated HTTPS ingress, private network, or equivalent boundary. Expose only the action-scoped route. Do not expose the full Gateway API or copy the Gateway token into the Agent platform.

If the Agent platform already speaks MCP, use the MCP Action integration instead. It launches from the same onboarded repository and follows this exact HTTP Action path.

Claim boundary

• This guide covers the generated local sandbox Runtime only.
• HTTP transport does not prove that every Agent path is mediated.
• An Action response is not an independently observed outcome.
• OUTCOME VERIFIED requires the configured separate Probe and a satisfied outcome predicate.
• Production Provider activation, broader permissions, and additional Action schemas remain separate product decisions.