Process API¶

Send a JPEG snapshot and get a print-quality score, warning and pause suggestions, and the minimum and recommended delays before your next snapshot.

Start with the Create Context API. Using the same context lets Gadget consider results from earlier snapshots when checking how the print is progressing.

HTTP Request¶

Use the full ProcessRequestUrl returned by the Create Context API, exactly as returned. It already includes the context ID. See retries and fallback URLs if that server is unavailable.

POST https://<your-process-host>.octoeverywhere.com/api/gadget/v1/process/{ID}

Authentication¶

No X-API-Key header is required. The context ID in the URL authorizes this request, so keep the URL private. Existing clients may continue sending the header, but processing uses the context's owning account regardless of that header. The owner's account and usage rules still apply.

Path Parameters¶

Request Body¶

Send exactly one image file in a multipart/form-data POST body; JPEG is recommended. The image file can be up to 6 MiB (6,291,456 bytes), excluding multipart overhead. The field name and filename can be anything; this example uses image and print.jpg.

Images must be no larger than 8,192 pixels on either side and 20 million pixels total. A normal webcam snapshot is sufficient.

Example Request¶

Replace the URL placeholder with the full ProcessRequestUrl and point curl at your JPEG file:

PROCESS_REQUEST_URL='PASTE_FULL_ProcessRequestUrl_HERE'

curl --request POST "$PROCESS_REQUEST_URL" \
    -F 'image=@print.jpg'

Let curl set Content-Type so it includes the required multipart boundary. For Python, the standalone HTTP example shows the upload, timing, and error handling using requests.

Successful Response¶

{
    "NextProcessIntervalSec": {
        "Minimum": 5,
        "Recommended": 20
    },
    "FasterInspectionSuggested": false,
    "PrintQuality": 9,
    "WarningSuggested": false,
    "PauseSuggested": false,
    "Score": 5
}

Which fields should I use?¶

The warning and pause flags are persistent recommendations. Your software decides how to act on them, including sending notifications, pausing the printer, and applying cooldowns. See Handling repeated suggestions.

Response Details¶

NextProcessIntervalSec¶

Use NextProcessIntervalSec.Recommended as the default inspection interval, taking the value from the latest Process API response. You can inspect faster than recommended, provided you wait at least NextProcessIntervalSec.Minimum seconds between calls.

For a custom interval, wait max(your_configured_interval, NextProcessIntervalSec.Minimum) seconds before sending the next snapshot. A fixed interval is supported for predictable usage. You can optionally follow FasterInspectionSuggested to temporarily use the recommended interval when Gadget detects a possible issue. If no custom interval is configured, use NextProcessIntervalSec.Recommended.

All print-hour pricing uses a 20-second interval: 180 inspection calls equal one print hour. Billing is based on inspection calls, so inspecting faster uses more calls, consumes the free allowance sooner, and increases paid usage costs. A 5-second interval uses four times as many calls per actual hour of printing as a 20-second interval.

FasterInspectionSuggested¶

FasterInspectionSuggested is an optional timing hint for apps that normally use a fixed inspection interval. You can ignore it and keep your configured interval for predictable usage, or use it to follow the same signal that makes OctoEverywhere inspect more frequently internally. Apps that already follow NextProcessIntervalSec.Recommended need no extra timing logic.

Gadget sets it to true when it has strong evidence of a possible issue and wants faster snapshots to build confidence. It can still be true on the response that first sets WarningSuggested or PauseSuggested; it is not itself a warning or pause command.

To opt in, choose your next delay after each successful response:

• If FasterInspectionSuggested is true, use the latest NextProcessIntervalSec.Recommended.
• If it is false or missing, return to your configured interval. Treating a missing field as false keeps clients compatible with older responses.
• Always wait at least the latest NextProcessIntervalSec.Minimum. This flag never permits calls below the minimum.

For example, with a configured interval in seconds:

intervals = response["NextProcessIntervalSec"]
next_delay = configured_interval
if response.get("FasterInspectionSuggested", False):
    next_delay = intervals["Recommended"]
next_delay = max(next_delay, intervals["Minimum"])

Use WarningSuggested and PauseSuggested to decide when to act; FasterInspectionSuggested only controls timing. Temporarily shortening the interval makes more inspection calls, which can consume the free allowance sooner and increase paid usage costs.

PrintQuality¶

PrintQuality ranges from 1 to 10, where 10 is perfect print quality.

Use it on printer displays, dashboards, or anywhere you show print status. For warnings and pause actions, use WarningSuggested and PauseSuggested instead of acting on this score alone.

WarningSuggested¶

WarningSuggested is true when Gadget is confident enough to recommend warning the user about a possible print issue.

Once raised, it remains true on subsequent responses until Gadget no longer detects an active warning condition.

Adjust the required confidence with WarningConfidenceLevel when creating the context. Gadget considers several snapshots over time, so a low PrintQuality does not immediately produce a warning. Timing depends on your inspection interval and confidence setting.

PauseSuggested¶

PauseSuggested is true when Gadget is confident enough to recommend pausing a print that has probably failed.

Once raised, it remains true on subsequent responses until Gadget no longer detects an active pause condition.

Adjust the required confidence with PauseConfidenceLevel when creating the context. Gadget waits for enough evidence before suggesting a pause; there is no fixed delay after a low PrintQuality result.

Handling repeated suggestions¶

WarningSuggested and PauseSuggested describe the current detection state for the print context. Each returns to false once its condition is no longer active. Gadget considers recent detections over time, so a single clean image may not clear a flag immediately; earlier detections must age out of its detection window.

Your integration owns the action policy. For example, you can:

• Notify once when a flag changes from false to true.
• Send reminders while it stays true, with a notification cooldown you choose.
• Track whether a pause was requested or confirmed to avoid repeated printer commands, and choose any delay between warning and pausing.

Keep this action state per print context. Sending a notification or pausing the printer does not clear either flag. The API does not apply an action cooldown or suppress suggestions because your application already acted. Repeated true values do not require repeating the action on every response.

Score¶

Most apps can ignore Score. It ranges from 0 (best) to 100 (worst) and includes recent results from this context.

Use it for custom analysis, such as smoothing or combining results. Use the quality score and suggestion flags for user-facing status and actions.

Error Response¶

Gadget API failures return a non-200 HTTP status with the common JSON error object. Connection failures and oversized requests rejected by the web server may not include this body.

{
    "ErrorType": "OE_IMAGE_DECODE_FAILED",
    "ErrorDetails": "The uploaded image could not be decoded."
}

API Key IP Restricted¶

HTTP 403 with ErrorType set to OE_API_KEY_IP_RESTRICTED means this request's public IP address is reserved for a different account's key. The check uses the context's owning key. Stop inspections and follow Error Handling; changing headers or switching URLs does not resolve the account conflict.

Free Usage Limit Reached¶

HTTP 429 with ErrorType set to OE_FREE_USAGE_LIMIT_REACHED means the monthly free allowance has been exhausted and either billing is not set up or Free Usage Only is enabled.

Stop sending inspections until the allowance resets, or until the account owner sets up billing and turns off Free Usage Only at OctoEverywhere.com/gadgetapi. Creating a new context or switching to the fallback URL does not reset the allowance.

Handle this error separately from temporary rate limiting. Do not retry it in a loop; a Retry-After header does not mean the monthly allowance has reset.

Context Unavailable¶

Stop processing on 404 OE_CONTEXT_NOT_FOUND, 410 OE_CONTEXT_EXPIRED, or 410 OE_CONTEXT_CANCELLED. These are context-state errors, so do not switch URLs or automatically create a replacement. See Context Management if your integration uses deadlines, extensions, or cancellation.

Rate Limited¶

For 429 OE_CONTEXT_RATE_LIMITED, wait at least the Retry-After number of seconds before retrying. This applies to both the normal minimum interval and an optional per-minute limit.

Calling Pattern¶

Send one snapshot at a time. After each successful request, wait for your inspection interval, then send the next snapshot while the print is running. See retries and fallback URLs and error handling for recovery steps.