stuntman / providers / http apis

HTTP APIs

Any REST, GraphQL or MCP API described once as a YAML plugin: routes, state, answers, callbacks and failures on cue.

Stands in for

  • Any REST or JSON API
  • GraphQL APIs
  • OAuth2 and PKCE providers
  • Session-cookie portals
  • Remote MCP servers
  • Signed webhook senders

Everything HTTP APIs gives you

  1. 01

    Routes as readable steps

    Each route reads receive, let, keep, wait, decide, respond, send. Edit in the route editor or the YAML; every change is validated first.

  2. 02

    State and data tables

    keep stores what the provider remembers between calls; data tables (people, flagged documents) feed answers through lookup().

  3. 03

    Auth like the provider

    OAuth2 client credentials with a token route, Basic, session cookies from a login route, and mTLS client certificates.

  4. 04

    Browser steps

    Plugins draw authorize pages (PKCE, OTP, pick a person) and push approvals the app polls. Agents pass them with authorize_as and approve_push.

  5. 05

    GraphQL and streams

    Routes share POST /graphql and answer by operation name. Answers can stream as SSE, NDJSON or plain chunks.

  6. 06

    Be an MCP server

    An mcp: block serves tools/list and tools/call on /<service>/mcp; each tool decides like a route. set_mcp_tool adds one.

  7. 07

    Signed webhooks

    send steps sign as hex HMAC, Stripe, Svix, GitHub or CloudEvents. Delays follow the environment's clock: advance_clock(by="30d").

  8. 08

    Idempotency and scenarios

    A repeated Idempotency-Key replays the first answer (409 on another body). Scenarios switch a service's behaviour by name.

  9. 09

    Catch unmatched calls

    Requests no route takes are kept with the closest route; route_from_request drafts the missing route from one.

The screens

Each number is a control or a reading on the real screen. Everything you can click there, your agent can do with a tool.

A route, step by step, with its YAML

A route, step by step, with its YAML: the HTTP APIs screen in Stuntman
1Routes of the plugin

One route per kind of request the provider takes, with its calls today and billing.

1 of 5
2Receive

Bearer token from the plugin's own token route; a missing body field answers 400 like the provider.

2 of 5
3Keep

State the provider remembers between calls, keyed by an expression. Refused calls change nothing.

3 of 5
4Decide

First match wins: conditions on body, state and data pick a named answer.

4 of 5
5The same file

The YAML beside the editor marks the changed lines. Try it runs a sample request without keeping anything.

5 of 5
  1. Routes of the plugin

    One route per kind of request the provider takes, with its calls today and billing.

  2. Receive

    Bearer token from the plugin's own token route; a missing body field answers 400 like the provider.

  3. Keep

    State the provider remembers between calls, keyed by an expression. Refused calls change nothing.

  4. Decide

    First match wins: conditions on body, state and data pick a named answer.

  5. The same file

    The YAML beside the editor marks the changed lines. Try it runs a sample request without keeping anything.

A browser step the plugin draws

A browser step the plugin draws: the HTTP APIs screen in Stuntman
1People from the plugin

Synthetic people with their certificates come from the plugin's data table.

1 of 5
2Broken on purpose

Pick a person whose certificate expired to see how the app handles it.

2 of 5
3One-time code

Any 6 digits pass; 000000 is refused on purpose.

3 of 5
4Authorize or Deny

Redirects to the app with code and state; the token call then checks the PKCE verifier.

4 of 5
5What Stuntman records

Each step lands on the timeline. Agents skip the page with authorize_as.

5 of 5
  1. People from the plugin

    Synthetic people with their certificates come from the plugin's data table.

  2. Broken on purpose

    Pick a person whose certificate expired to see how the app handles it.

  3. One-time code

    Any 6 digits pass; 000000 is refused on purpose.

  4. Authorize or Deny

    Redirects to the app with code and state; the token call then checks the PKCE verifier.

  5. What Stuntman records

    Each step lands on the timeline. Agents skip the page with authorize_as.

Webhook signing, idempotency and the clock

Webhook signing, idempotency and the clock: the HTTP APIs screen in Stuntman
1Sign like the provider

Hex HMAC, hex with timestamp, Stripe, Svix, GitHub or CloudEvents, with the secret and header the app checks.

1 of 4
2Break every send

Wrong signature, old timestamp, no signature, sent twice or out of order, until set back to none.

2 of 4
3Idempotency-Key

The same key gets the first answer again with no webhook; the same key with another body gets 409.

3 of 4
4The environment's clock

Move it 1 h, 1 day or 30 days: waiting webhooks go out and now() follows. Back to real time resets it.

4 of 4
  1. Sign like the provider

    Hex HMAC, hex with timestamp, Stripe, Svix, GitHub or CloudEvents, with the secret and header the app checks.

  2. Break every send

    Wrong signature, old timestamp, no signature, sent twice or out of order, until set back to none.

  3. Idempotency-Key

    The same key gets the first answer again with no webhook; the same key with another body gets 409.

  4. The environment's clock

    Move it 1 h, 1 day or 30 days: waiting webhooks go out and now() follows. Back to real time resets it.

Break it on purpose

The failures you need to test, exactly when you ask: from the screen or by a tool call, each one shown on the timeline with who caused it.

  • Any named answer

    The next N calls (or the next 10 minutes) get a declined, expired or not-found answer

    force_answer {answer, count | for, route}
  • Network failures

    Connection reset, empty reply or a timeout

    force_answer reset | empty | timeout
  • Server errors

    500 or 503 from the provider

    force_answer 500 | 503
  • HTML error page

    A 200 whose body is an HTML error page, as a proxy in front of the provider sends

    force_answer html
  • Expired tokens

    Every token and session cookie becomes invalid; the next call gets 401

    expire_tokens
  • Rate limit

    Calls above the rate get 429 with Retry-After

    set_service rate=10/s
  • A share of failures

    A random share of calls fails

    set_service fail_share=25%
  • Slow provider

    Every answer waits a range of latency

    set_service latency=2s..4s
  • Broken stream

    Half the parts then a dropped connection, or 2 s more per part

    force_answer cut | slow
  • MCP session expired

    The next MCP request gets 404 and the client must start a new session

    force_answer session_expired
  • Bad webhooks

    Wrong signature, old timestamp, unsigned, sent twice or out of order

    set_service webhook_provoke
  • Person says no

    The authorize page is denied, or the push approval is rejected or times out

    authorize_as deny=true, approve_push answer=reject | timeout

Why not the real sandbox

Your AI agent drives it

Claude Code, Codex or any MCP client connects to /mcp (or calls /api over plain HTTP), sets the stand-in up, breaks it on cue and reads what your app did.

you

Make sure checkout retries when the payments API times out, and that the retry succeeds.

force_answer{"service": "example-payments", "answer": "timeout", "count": 1, "route": "POST /v1/charges"}
→ ok the next POST /v1/charges times out
wait_for_api_call{"service": "example-payments", "route": "POST /v1/charges", "answer": "create_charge"}
→ ok the app retried: 201 create_charge after the timeout

MCP tools

  • list_api_callsCalls any plugin answered, with sentence and answer name
  • get_api_callWhat the app sent, what Stuntman answered, steps and webhooks
  • wait_for_api_callWaits for the next call to a service, route or answer
  • force_answerThe next calls get a named or generic answer
  • expire_tokensEvery token of a service becomes invalid
  • set_routeCreates or replaces a route, validated first
  • try_routeRuns a route on a sample request; nothing is kept
  • list_unmatchedRequests no route took, with the closest route
  • authorize_asCompletes a waiting page as a person
  • advance_clockMoves the environment's clock forward

The same over HTTP

  • GET/api/apis/calls
  • GET/api/apis/calls/wait
  • POST/api/apis/{service}/force
  • POST/api/plugins/{service}/try
  • GET/api/apis/unmatched
  • POST/api/clock/advance