Sandbox environment

Overview

The sandbox lets you exercise your integration without running real asset processing or consuming processing credits. It is not a separate host or base URL. You select the sandbox by using a sandbox API key: the same base URL and the same paths behave as a sandbox when the request is authenticated with an sk_test_ key. Sandbox keys unlock two capabilities:

A simulationDelaySeconds query parameter on submission creation, to control timing.
A POST /api/sandbox/events/fire endpoint, to dispatch synthetic webhook events to your subscriptions without real processing.

Sandbox submissions are excluded from Insights — their canned results never affect your workspace’s counts, rates, or processing durations.

Using a sandbox key

Use your sk_test_ key against the normal base URL and the normal endpoints. The asset filename selects the outcome to simulate — see Choosing a test scenario. As with live submissions, sidekickIds is required (at least one), though the sandbox does not actually run the named sidekicks.

curl -X POST https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions \
  -H "X-API-Key: sk_test_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "blobPath": "11111111-1111-1111-1111-111111111111/__sandbox_pass__" }
    ],
    "sidekickIds": ["<sidekick-id>"]
  }'

A live (sk_live_) key calls the same endpoints but cannot use the sandbox-only features described below.

Choosing a test scenario

Sandbox submissions never run real analysis. Instead, you pick the outcome by embedding a magic marker in the asset’s filename. The marker selects a canned result that flows through the normal read endpoints — submission status, per-asset issues, and retry — exactly as a real processing result would.

Every asset in a sandbox submission must contain one of the markers below in its filename. A sandbox submission whose asset filename has no recognised marker is rejected with 400 Bad Request:

{ "detail": "Sandbox API keys only accept magic filenames. '<filename>' must contain one of: __sandbox_pass__, __sandbox_advisory__, __sandbox_fail__, __sandbox_error__, __sandbox_retryable_error__, __sandbox_pending__. See the sandbox documentation for details." }

Live (sk_live_) keys ignore these markers entirely — they run real processing regardless of filename.

blobPath always has the form {asset-id}/{filename}, where {asset-id} is a UUID. The marker goes in the filename — the part after the /. The simplest form is to use the marker as the whole filename, e.g. 11111111-1111-1111-1111-111111111111/__sandbox_pass__. Because the sandbox never reads a real file, you do not need to upload anything first for sandbox submissions — any UUID works as the asset id. (For live submissions you obtain blobPath from the upload endpoints instead.)

Filename marker	Submission status	Asset outcome	Issues produced	Retryable
`__sandbox_pass__`	`complete`	Clean pass	None	—
`__sandbox_advisory__`	`complete`	Passes with advisories	2 — one `minor`, one `info`	—
`__sandbox_fail__`	`complete`	Completes but carries blocking issues	3 — one `critical`, two `major`	—
`__sandbox_error__`	`failed`	Non-retryable processing failure	None	No
`__sandbox_retryable_error__`	`failed`	Transient processing failure	None	Yes
`__sandbox_pending__`	`processing`	Stays in processing, never finalises	None	—

A few details worth noting:

__sandbox_fail__ still reports complete. A “fail” here means the asset finished but surfaced critical/major issues — the submission status is complete and the issues appear via the asset issues endpoint. Use it to exercise issue-handling logic.
__sandbox_error__ vs __sandbox_retryable_error__. Both drive the submission to failed. The error variant is a permanent failure (isRetryable: false); the retryable variant sets isRetryable: true so you can exercise the retry endpoint. The submission’s errorMessage is Sandbox simulated error or Sandbox simulated retryable error respectively.
__sandbox_pending__ leaves the submission in processing indefinitely — useful for testing polling timeouts and real-time status updates.
Mixed-scenario submissions. When a submission contains assets with different markers, the worst outcome decides the overall submission status, in this order (worst first): error → retryable_error → fail → advisory → pass → pending. Each asset still carries its own issues and per-asset failure fields.

Example: testing the issue path

curl -X POST https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions \
  -H "X-API-Key: sk_test_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "blobPath": "11111111-1111-1111-1111-111111111111/__sandbox_fail__" }
    ],
    "sidekickIds": ["<sidekick-id>"]
  }'

Poll the submission to completion, then read the issues for the returned asset — you will get one critical and two major issues to drive your review UI or compliance checks.

Example: testing the retry path

curl -X POST https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions \
  -H "X-API-Key: sk_test_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "assets": [
      { "blobPath": "11111111-1111-1111-1111-111111111111/__sandbox_retryable_error__" }
    ],
    "sidekickIds": ["<sidekick-id>"]
  }'

The submission ends as failed with isRetryable: true. Call the retry endpoint for that asset to exercise your recovery flow: the sandbox simulates a successful retry, so the asset recovers and the submission moves to complete with isRetryable: false. The retry is single-use — once the asset has recovered it is no longer in a failed state, so a second retry returns 409. Submit __sandbox_error__ instead to verify that a non-retryable failure is rejected by the retry endpoint with 409.

Simulating processing time

Add the simulationDelaySeconds query parameter to a submission-create request to delay when the submission reaches a terminal state. This is useful for exercising your polling and webhook-handling logic.

curl -X POST "https://api.northell.io/nhl/prod/mediamagic-verify-integrations/api/submissions?simulationDelaySeconds=5" \
  -H "X-API-Key: sk_test_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{ "assets": [ { "blobPath": "11111111-1111-1111-1111-111111111111/__sandbox_pass__" } ] }'

The parameter is camelCase: simulationDelaySeconds.
Accepted range is 0 to 30 seconds. Default is 0.
It works only with a sandbox key. Sending it on a live key returns a 400.

Firing synthetic webhook events

To test your webhook handler end to end, fire a synthetic event for an existing submission’s assets. The endpoint dispatches the event to every matching subscription in your workspace, exactly as a real processing event would, but without running any processing.

POST /api/sandbox/events/fire

Request body (camelCase):

{
  "eventType": "asset.processing.failed",
  "submissionId": "550e8400-e29b-41d4-a716-446655440000",
  "errorMessage": "Simulated processing failure"
}

Field	Required	Notes
`eventType`	Yes	One of `asset.processing.completed` or `asset.processing.failed`
`submissionId`	Yes	A submission that exists in your workspace
`errorMessage`	No	Optional message, used with `asset.processing.failed`

Response 200:

{
  "dispatched": 2
}

dispatched is the number of subscriptions notified across all of the submission’s assets. This endpoint is sandbox-only. Behaviour by condition:

Condition	Result
Sandbox key, submission in workspace	200 with `dispatched` count
Live key	403
`submissionId` not found in your workspace	404
Malformed request body	422

Testing the failure path

There are two complementary ways to exercise failure handling in the sandbox. To test the processing-result read path, submit an asset with the __sandbox_error__ or __sandbox_retryable_error__ marker (see Choosing a test scenario) and read the failure back from the submission status. To test webhook delivery end to end, subscribe a webhook, create a submission, then fire an asset.processing.failed event and confirm your endpoint received it.

import requests

API_BASE = "https://api.northell.io/nhl/prod/mediamagic-verify-integrations"
api_key = "sk_test_your_sandbox_key"


def test_failure_webhook(submission_id: str) -> None:
    """Subscribe, fire a synthetic failure event, and confirm dispatch."""
    # 1. Subscribe to the failure event.
    sub = requests.post(
        f"{API_BASE}/api/webhooks/subscriptions",
        headers={"X-API-Key": api_key},
        json={
            "endpointUrl": "https://your-domain.com/webhooks/test",
            "eventTypes": ["asset.processing.failed"],
            "description": "Sandbox failure test",
        },
    )
    secret = sub.json()["secret"]
    print(f"Subscribed; verify deliveries with secret {secret}")

    # 2. Fire a synthetic failure for an existing submission's assets.
    fired = requests.post(
        f"{API_BASE}/api/sandbox/events/fire",
        headers={"X-API-Key": api_key},
        json={
            "eventType": "asset.processing.failed",
            "submissionId": submission_id,
            "errorMessage": "Simulated processing failure",
        },
    )

    dispatched = fired.json()["dispatched"]
    assert dispatched >= 1, "expected at least one subscription to be notified"
    print(f"Dispatched failure event to {dispatched} subscription(s)")
    print("Now assert your endpoint received an asset.processing.failed event")

The delivered webhook payload follows the standard shape documented in Webhook subscriptions: an outer type of asset.processing.failed, with a snake_case data object containing asset_id, submission_id, workspace_id, status of "failed", and error_message.

Key differences from production

Aspect	Sandbox (`sk_test_` key)	Production (`sk_live_` key)
Selection	API key prefix `sk_test_`	API key prefix `sk_live_`
Base URL and paths	Same as production	Same as sandbox
Processing	No real analysis or credits consumed; outcome chosen by filename marker	Real processing
Asset filename	Must contain a `__sandbox_*__` scenario marker	Real filename, no marker required
Webhook events	Can be fired synthetically via `/sandbox/events/fire`	Emitted by real processing
Timing control	`simulationDelaySeconds` (0–30) on submission create	Not available

Best practices

Use a sandbox key for all integration testing before switching to a live key.
Pick the outcome you want to test with the filename marker — __sandbox_fail__ for issue handling, __sandbox_retryable_error__ for retries, __sandbox_pending__ for polling timeouts.
Exercise your webhook handler by firing asset.processing.failed against an existing submission.
Use simulationDelaySeconds to test polling and webhook timing.
Verify webhook signature handling against the secret returned when you create a subscription.

Troubleshooting

Sandbox submission rejected with 400

A sandbox key requires every asset filename to contain a scenario marker (e.g. __sandbox_pass__). Add one of the markers from Choosing a test scenario to the filename portion of blobPath.
The marker must appear after the first / in blobPath — that is the filename the sandbox inspects.

Webhook not delivered

Ensure your endpoint is publicly reachable and returns 200
Confirm the subscription’s eventTypes includes the event you fired
Check that dispatched was at least 1 in the fire response
Review delivery history via the subscription’s deliveries endpoint

simulationDelaySeconds rejected

The parameter is camelCase: simulationDelaySeconds
The value must be between 0 and 30
A 400 means it was sent on a live key — use a sandbox (sk_test_) key

Fire endpoint returns 403 or 404

403 means you used a live key; sandbox events require a sk_test_ key
404 means the submissionId does not exist in your workspace

Ready for production?

Switch to your live (sk_live_) key against the same endpoints. Create or manage keys in the control plane, or contact support at https://support.iclear.ai/.

Getting Started

Core Concepts

Guides

Reference

API Endpoints

Overview

Using a sandbox key

Choosing a test scenario

Example: testing the issue path

Example: testing the retry path

Simulating processing time

Firing synthetic webhook events

POST /api/sandbox/events/fire

Testing the failure path

Key differences from production

Best practices

Troubleshooting

Sandbox submission rejected with 400

Webhook not delivered

simulationDelaySeconds rejected

Fire endpoint returns 403 or 404

Ready for production?

​Overview

​Using a sandbox key

​Choosing a test scenario

​Example: testing the issue path

​Example: testing the retry path

​Simulating processing time

​Firing synthetic webhook events

​POST /api/sandbox/events/fire

​Testing the failure path

​Key differences from production

​Best practices

​Troubleshooting

​Sandbox submission rejected with 400

​Webhook not delivered

​simulationDelaySeconds rejected

​Fire endpoint returns 403 or 404

​Ready for production?

Overview

Using a sandbox key

Choosing a test scenario

Example: testing the issue path

Example: testing the retry path

Simulating processing time

Firing synthetic webhook events

POST /api/sandbox/events/fire

Testing the failure path

Key differences from production

Best practices

Troubleshooting

Sandbox submission rejected with 400

Webhook not delivered

simulationDelaySeconds rejected

Fire endpoint returns 403 or 404

Ready for production?