What this makes possible
The workflow API is useful when your product needs a completed process, not another raw model response. A published workflow can already contain the input form, prompts, model choices, tool calls, branches, retries, and output selection that turn a capability into a repeatable result. The API runs the same immutable workflow version available on the marketplace, under the same input, funding, execution, and failure rules, so an integration does not create a private fork that quietly drifts away from the product a buyer can inspect.
A production integration begins with a scoped secret and the live workflow contract. Your application fetches the selected product immediately before execution, validates against its current input schema, and starts one asynchronous run with an idempotency key that represents the business action. A 202 response means the request was accepted, not completed, so the application stores the run identifier and follows canonical status. Simple clients can poll every one to three seconds; richer products can read ordered events or accept signed webhooks. Only a terminal run should trigger downstream delivery, accounting, or user-facing success.
The abstraction is a product, not a model call
A model API exposes a general capability and leaves the surrounding product work to your team. You still have to define the prompt, choose tools, validate input, sequence calls, recover from failures, decide which intermediate value is the answer, and operate that logic after launch. A workflow API moves that configured process behind one product contract. This is most valuable when the workflow creator has real domain knowledge or when the process is involved enough that reproducing it would become a small application of its own.
That does not mean treating a workflow as an opaque magic endpoint. Before the first production run—and again whenever the active version may have changed—fetch the workflow detail. It exposes the current input schema, pricing, provider and credential requirements, version state, and whether the caller is entitled to execute it through the API. Build the request from that schema; there is no universal field such as topic, and unknown keys are rejected so a misspelling does not silently degrade the result.
The public product page provides a useful human companion to the machine contract. A product manager or customer can inspect what the workflow claims to do, while the backend resolves the exact schema and version used for execution. Because marketplace runs and programmatic runs share the same engine, funding rules, and immutable versions, the explanation shown to a buyer and the operation called by code stay connected.
Design for acceptance, progress, and completion
POST /runs returns 202 Accepted with a run id and polling URLs after the request passes synchronous checks. That response is evidence that Edgaze accepted the work; it is not evidence that the work succeeded. The run can still finish, fail, be cancelled, lack wallet funding after acceptance, or stop at a compute limit. A correct UI therefore moves from submitted to running and only shows success after GET /runs/{id} or a verified terminal event reports completion.
Polling is often enough for a first integration. Store the run id beside your own job or customer record, query status every one to three seconds while the user is waiting, and back off or move the work to a background process when the request outlives the screen. Ordered run events add step-level visibility for a dashboard or support investigation. Webhooks are better when the application should react without keeping a poller alive, but they require signature verification against the exact raw request bytes, replay protection, and idempotent handling.
Network ambiguity is a billing problem as well as a reliability problem. Every new integration should send an idempotency key for each logical run. Repeating the same workflow, normalized inputs, and version under that key returns the original accepted run; changing the request under the same key returns a conflict. A failed run remains the result of that key, so a deliberate second execution requires a new key. This prevents an ordinary client timeout from becoming duplicate work, duplicate external side effects, or a second charge.
Make cost, access, and version drift explicit
A scoped key can have separate execute and read permissions, plus optional daily, monthly, or lifetime spend caps. Those controls solve different problems: scope limits what a leaked or misused key can do, while a spend cap limits the economic exposure. A cap can reject a run before it starts, but it does not replace checking the workflow's current displayed price or maintaining enough wallet or eligible bundle funding for the accepted version.
Version pinning is equally important for integrations that parse outputs or automate consequential work. Every API run resolves to one immutable version: an explicit entitled version, the caller's pinned access, or the current active version in that order. Workflow detail exposes pinnedVersionId, activeVersionId, and updateAvailable so the application can detect drift. When an update is available, review the new input and output shapes before accepting it; publishing a new creator version should not silently change a buyer who is pinned to an older contract.
Finally, code should model the documented terminal outcome rather than infer billing from the initial POST. Successful paid runs settle the displayed price. Ordinary failures and cancellations do not keep the creator margin, while a run stopped at its compute limit is shown separately because already-consumed compute may remain. Keeping run status, charge information, and a human-readable failure reason together gives support and finance teams something concrete to audit when a workflow does not end as expected.
Ship one workflow API integration
Start with one workflow and one narrow user journey. Wire the integration around the live contract and durable run identifier before adding background scheduling or a catalog browser. That gives you a correct execution path first and makes retries, spending, and completion behavior visible in development.
Issue a secret in the Developer console, give it only the scopes the service needs, and set spend boundaries that match the environment. Keep the plaintext in a secrets manager because Edgaze shows it only once and a leaked key should be revoked rather than recovered. Open API keys. Set the bearer token against the documented production base URL and make a small authenticated discovery request before integrating a workflow. Treat 401, insufficient scope, and entitlement errors as different operational problems rather than retrying every response. Start the API quickstart.
Fetch the live input schema immediately before the POST, validate locally, and send a stable Idempotency-Key for the logical request. Store the returned run id and status URL; reusing the same key with the same request retrieves the original acceptance rather than creating another billable run. See the create-run contract. Poll canonical status for a simple client, or verify the raw body and HMAC signature of a webhook before updating downstream systems. Webhook delivery is at least once and ordering is not guaranteed, so deduplicate on the delivery id and reconcile missed terminal runs when correctness depends on it. Configure webhooks.