Gadget API Developer Overview¶

Add Gadget to your app in three steps: create a context for a print, send webcam snapshots, and use the results to warn the user or pause the print. Start a new context for each print.

For API keys, pricing, free usage, and privacy, see the Gadget API overview.

API Overview¶

Include your API key in the X-API-Key header on both API calls.

1. Create a Print Context¶

A context keeps track of one print. Call Create Context when the print starts, then reuse that context for all snapshots from that print. Creating a context is free.

The response includes:

• ContextId: the ID for this print's context.
• ProcessRequestUrl: the full URL to send snapshots to. It already includes the context ID.
• FallbackProcessRequestUrl: a backup URL for the same context. Keep it for connection or server failures.

2. Send a Snapshot¶

Send one JPEG image to ProcessRequestUrl as a multipart/form-data POST request. The Process API has a complete upload example.

Gadget's temporal model combines the latest image analysis with earlier results from the print. This lets it follow how the print develops over time.

Use PrintQuality to display print status, and WarningSuggested or PauseSuggested to decide when to warn the user or pause the print. Your software takes those actions. See Which Fields Should I Use? for a quick guide to the response.

3. Wait and Repeat¶

Use a 20-second interval by default. After each response, wait at least the latest NextProcessIntervalSec before sending another snapshot. If that minimum is longer than your chosen interval, wait longer.

Keep sending snapshots while the print is running. See inspection timing for custom intervals and how they affect usage.

SDKs¶

Using Python? Start with our Gadget Python SDK.

You can also call the APIs directly from your preferred language. The endpoint pages include request examples, and the standalone Python HTTP example shows the full flow without depending on the SDK.

Error Handling¶

API errors return a non-200 HTTP status and a JSON body:

{
    "ErrorType": "OE_INTERNAL_ERROR",
    "ErrorDetails": "A string with error details."
}

Use ErrorType to decide what to do. ErrorDetails explains the specific problem.

Retry After a Delay¶

Wait until your next inspection interval before retrying. Avoid immediate retry loops.

Fix the Request or Account¶

Free Usage Limit¶

The free allowance applies across the account. Creating another context or switching processing URLs does not reset it.

To continue with paid usage, the account owner can set up billing and turn off Free Usage Only. If billing is already set up, they only need to turn off that setting. Otherwise, wait for the next monthly allowance.

IP Restrictions¶

The first successfully authenticated API key used from a public IP address claims that IP. Other keys cannot use it, including keys from accounts sharing the same public IP. The same key can still use multiple IPs.

Use your original key, or contact our team if that key is unavailable or the IP is shared with another account. Creating another key, setting up billing, or changing Free Usage Only does not remove the restriction.

Retries and Fallback URLs¶

Start with ProcessRequestUrl. If a connection or server failure prevents processing, switch to FallbackProcessRequestUrl and keep using it for the rest of that print's context. The fallback can route requests to another region.

When you receive a JSON API error, check Error Handling first. Invalid requests, account problems, IP restrictions, and usage limits need the actions listed there; switching URLs won't fix them.

Keep the same context when retrying or switching URLs, and wait between attempts. Use your chosen inspection interval, defaulting to 20 seconds, and respect the most recent NextProcessIntervalSec.