Create a run -- idempotencyKey replay returns the existing run (any status) with replayed:true instead of creating a new one

customer-test friction #4 (docs/product/reviews/2026-09-04-customer-test): dispatch is woken immediately for the run's workspace rather than left for the next poll tick, and the run always returns immediately unless wait asks otherwise (either as this query parameter or as a body field of the same name -- the query parameter wins if both are given). wait=true (or a bare ?wait) waits up to the default of 20 s; a number is seconds, clamped to [0, 60]. Returns the result inline, in the same run shape this endpoint already returns, once it reaches a terminal status within wait seconds. If it is still queued/running when the window ends, returns that queued/running run instead, exactly as with no wait at all -- poll it with GET /v1/runs/{runId} or runs_get. A 201 can carry status:"failed" (a pre-dispatch denial such as endpoint_not_found or a validation_error) -- check the run's own status and error fields, never the HTTP status code alone, to know whether it actually ran.

post/v1/runs

Request

  • Base URL: https://api.looot.ai
  • URL: https://api.looot.ai/v1/runs
  • Auth: HTTP bearer

Query parameters

boolean
OR
number

Seconds to wait for a terminal result inline (default 20 when true/bare, max 60). Omit entirely for the pre-existing immediate-return behavior.

Headers

Idempotency-Keystring

Alternative to the request body's idempotencyKey field. Either satisfies the (still mandatory) requirement; if both are present, they must be equal or the request is a 400.

Request body

endpointIdstring required

The catalog endpoint id to run

inputobject required

Arbitrary key/value input, validated against the endpoint's own input schema

idempotencyKeystring

Required, unless supplied instead as the Idempotency-Key request header (either satisfies the requirement; supplying both requires them to match, or the request is a 400). A replay with the same key and the same body returns the original run (replayed:true); the same key with a different body is a 409. Never auto-generated by the gateway -- see the report's decision options for why.

outputobject

Optional output selection/mapping pin; same shape as an inspected endpoint's outputMappingPin

Response

Run created (or the existing run replayed, any status, with replayed:true). A 201 is not itself success -- a pre-dispatch denial (endpoint_not_found, validation_error) also answers 201 with status:"failed" and a populated error; read the body, not the status code.

Changes

No recorded changes to this operation across all 1 revision of this API.