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¶

You only need to make two API calls: 1. create a context, 2. process an image for failures.

1. Create a Print Context¶

A context keeps track of one print. Call Create Context with your X-API-Key header and an empty JSON object, {}. Reuse the returned 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.

Keep the context ID and URLs private: they grant access to that print's context.

2. Send a Snapshot¶

Send one JPEG image to ProcessRequestUrl as a multipart/form-data POST request. No API key is needed for this call. 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.

Both flags remain true across responses while their respective issue is detected, and return to false once that condition is no longer active. Gadget considers recent detections, so one clean image may not clear them immediately. Your integration decides when to act and handles notification cooldowns, reminders, and duplicate pause commands. See Handling repeated suggestions.

3. Wait and Repeat¶

Use NextProcessIntervalSec.Recommended as the default interval from the latest response. Any custom interval must be at least NextProcessIntervalSec.Minimum, which is five seconds by default. Faster inspections use more calls and increase paid usage costs.

Keep sending snapshots while the print is running, then stop. Contexts are cleaned up automatically after 14 days; you do not need a separate cleanup call.

For fixed intervals and the optional FasterInspectionSuggested timing hint, see inspection timing.

Optional Context Controls¶

Need a time limit, a per-minute limit, or a reference ID for your own system? Context Management covers those options, reading a context's state, extending its lifetime, and canceling it. These controls are optional; the two-call flow above is enough to get started.

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. Use the HTTP endpoints for the optional context-management calls.

Error Handling¶

Gadget 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 and can change. Connection failures and proxy errors may not include this JSON body.

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¶

Each Gadget server reserves a public IP address for the first valid API key used from it, for a fixed four-hour window. Other keys cannot use that IP on the same server during the window, including accounts sharing the same public IP. The same key can use multiple IPs. Process applies this rule using the context's owning key, even though the request has no key header.

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 current 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 the most recent NextProcessIntervalSec.Recommended by default, or a custom inspection interval that is at least NextProcessIntervalSec.Minimum. Before the first successful response, use 20 seconds as the default delay between attempts.

A timed-out request may already have been processed and counted. Wait before sending a fresh snapshot instead of immediately replaying the same image.