Rustbox API Guide: Sync, Async, and Webhook Patterns for Code Execution
A practical Rustbox API guide explaining when to use sync execution, async polling, and webhooks for code execution workflows.
The Rustbox API gives you three ways to get code execution results: wait for the result in the request, submit and poll later, or receive a webhook when execution completes. The right choice depends on your product flow, not on which pattern sounds more advanced.
The three Rustbox result patterns
Every code execution workflow starts the same way: your backend sends code, language, and optional input to Rustbox. The difference is how your product receives the result.
Sync execution waits for a completed result in the request. Async execution returns an ID immediately so your backend can poll later. Webhooks push the completed result to your endpoint after execution finishes.
These patterns are not competitors. Most mature products use more than one. A playground might use sync for the Run button, async for final grading, and webhooks for background batch jobs.
Architectural Flow Patterns
Rustbox enables flexibility in communication patterns. Review the structural grid below to align your architecture with the correct performance and synchronization requirements:
Block & Wait
POST `/submit?wait=true`
Client -> Request -> [Runs Sandbox] -> Returns Result- ✓ ~36ms latency
- ✓ No state tracking
Submit & Poll
POST `/submit` → GET `/result/<id>`
Client -> Submits -> Returns ID -> Polls -> Result- ✓ Instant ID return
- ✓ Polling checks ~50ms
Fire & Callback
POST `/submit` → POST Callback
Client -> Submits -> [Async Run] -> Calls Webhook- ✓ High-volume scale
- ✓ Avoid open sockets
When to use sync code execution
Use sync execution when a human is actively waiting and the code is expected to finish quickly. This fits playgrounds, lesson examples, candidate "Run tests" buttons, and internal tools where the result is part of the current screen.
curl -s -X POST "https://rustbox.orkait.com/api/submit?wait=true" \
-H "Content-Type: application/json" \
-H "X-API-Key: rb_live_your_key_here" \
-d '{"language": "python", "code": "print(42)"}'The main benefit is simplicity. One request goes out, one result comes back, and the UI can render output immediately. The tradeoff is that the request stays open while execution runs.
When to use async polling
Use async execution when the result can arrive after the initial request. This fits final submissions, batch grading, long-running internal jobs, and flows where your UI can show "running" while the backend checks status.
# Submit
curl -s -X POST "https://rustbox.orkait.com/api/submit" \
-H "Content-Type: application/json" \
-H "X-API-Key: rb_live_your_key_here" \
-d '{"language": "python", "code": "print(42)"}'
# Poll
curl -s "https://rustbox.orkait.com/api/result/<id>" \
-H "X-API-Key: rb_live_your_key_here"Async polling gives your product more control. You can store the execution ID, show progress, retry status checks, and resume after a page refresh. It is also easier to connect with your own database records.
When to use Rustbox webhooks
Use webhooks when polling would be wasteful or awkward. If your system submits many jobs and does not need the result in the same request, webhooks let Rustbox call your backend when execution completes.
This is useful for high-volume grading, background AI workflows, nightly checks, and products where the user may leave the page before the job finishes.
Webhooks should be treated as backend infrastructure. Verify signatures, handle retries safely, and store delivery outcomes with your own job records. The Rustbox webhook docs show the headers, signed content shape, and delivery behavior.
Sync vs async vs webhooks: a decision table
| Pattern | Use when | Avoid when | Example |
|---|---|---|---|
| Sync | The user is waiting in the current UI. | You expect large batches or delayed work. | Playground run button. |
| Async | You want to store an ID and check later. | The UI needs an immediate answer. | Final assignment grading. |
| Webhooks | Your backend should receive completed results. | You cannot expose a stable HTTPS endpoint. | Batch processing pipeline. |
The safest default is to start simple. Use sync for the first prototype, async once you need saved execution state, and webhooks when polling becomes operational noise.
Frequently asked questions
Is sync execution always faster than async execution?
Not necessarily. Sync is simpler for the caller because the result comes back in one request. Async can be better for product flows that need persistence, retries, or background processing.
Do webhooks replace polling completely?
Webhooks reduce polling, but many products still keep a result endpoint as a fallback for retries, support workflows, and manual refreshes.
Where should I store Rustbox execution IDs?
Store execution IDs alongside your own domain records: candidate attempts, student submissions, agent tool calls, or internal jobs. That makes support and auditing much easier.
Choose your Rustbox API pattern
Read the API reference for request fields, response fields, status codes, and webhook verification details.
Open API docs
