Context Management¶

For a basic integration, create a context with {} and send images to the Process API. Contexts are cleaned up automatically after 14 days. You do not need to configure limits or call these management APIs.

The optional settings and APIs below help when you want to share a context with a LAN client, set limits for a print, extend its lifetime, or stop processing early.

Sharing Access with a LAN Client¶

Keep your Gadget API key on your server. The context ID provides access to one print without giving the client your account's API key:

1. Your server calls Create Context, using X-API-Key. It can set a lifetime based on the estimated print duration, a processing rate, and your own reference ID.
2. Your server sends the returned ContextId, ProcessRequestUrl, and FallbackProcessRequestUrl to the LAN client.
3. The client sends snapshots to ProcessRequestUrl without an API key and follows the returned inspection timing. Use the fallback URL according to the retry guidance.
4. If needed, the client can read the context's state or cancel it using its ID. Only your server, with the owning API key, can extend its lifetime.

Processing remains subject to the owning account's key, billing, IP restrictions, and free-usage policy. The LAN client does not need to use the same public IP as your server, but the account's IP restrictions still apply. See Error Handling for account restrictions and recovery.

Optional Creation Settings¶

Include any of these fields in the Create Context request. All are optional; omitting a field or sending null leaves it unset.

{
    "ExpireAfterSec": 86400,
    "MaxProcessCountPerMinute": 2,
    "ReferenceId": "farm-7:print-1842"
}

ExpireAfterSec is an input only. The service converts it to an absolute UTC deadline and returns ExpiresAtUtc. Processing images does not move this deadline. The other creation settings, including confidence levels, cannot be changed afterward.

ReferenceId keeps its original casing and does not need to be unique. It does not grant access to a context, and there is no public lookup by reference ID. Store the returned ContextId alongside your own reference. Do not put credentials in the reference.

Processing Rate and Usage¶

Continue to follow NextProcessIntervalSec.Minimum and Recommended from each Process response. The minimum is at least five seconds, or longer when your per-minute limit requires it. For example, two attempts per minute means a minimum of 30 seconds. A limit above 12 does not allow intervals below five seconds.

The per-minute limit counts attempts admitted by that rate check, including attempts that later fail image decoding or inference. A request rejected by the rate check does not consume another slot. On HTTP 429 OE_CONTEXT_RATE_LIMITED, wait at least the number of seconds in Retry-After before retrying.

This counter is local to each Gadget server. Concurrent requests to one server share it, another server has its own counter, and a restart clears it. Use the assigned processing URL during normal operation. This is not an exact total inspection or spending budget.

Only successful inspections count toward metered usage. Creating, reading, extending, or canceling a context is not metered and does not reserve inspections. Context limits and extensions do not change pricing or free usage, reset account usage, or remove the account's processing restrictions.

Read Context Information¶

Use this endpoint to read the context's current settings and state. Replace {id} with ContextId. No API key or request body is required. It remains available if billing blocks processing, and expired or canceled contexts remain readable until cleanup removes them.

POST https://gadget-pv1-oeapi.octoeverywhere.com/api/gadget/v1/contextinfo/{id}

{
    "ContextId": "uYZkEP0g22nPZwtCj6ASWef9Lpmh81Ahs1mnAdw4Z7PlDFbOK6",
    "CreatedAtUtc": "2026-10-23T16:00:00Z",
    "ExpiresAtUtc": "2026-10-24T16:00:00Z",
    "MaxProcessCountPerMinute": 2,
    "ReferenceId": "farm-7:print-1842",
    "WarningConfidenceLevel": 3,
    "PauseConfidenceLevel": 3,
    "IsCancelled": false,
    "IsExpired": false
}

IsCancelled and IsExpired are independent; both can be true. This response contains public context information only, with no account or API-key details. See confidence settings for how the warning and pause levels affect detection.

Extend a Context¶

Call this from your server when a print needs more time. Replace {id} with ContextId and send the same owning API key used to create the context. The context ID alone cannot authorize an extension. A different account or creating key receives HTTP 404 OE_CONTEXT_NOT_FOUND.

POST https://gadget-pv1-oeapi.octoeverywhere.com/api/gadget/v1/extendcontext/{id}
X-API-Key: prod_YOUR_API_KEY
Content-Type: application/json

{
    "ExpireAfterSec": 172800
}

This requests a total lifetime of two days from creation. For a context created at 2026-10-23T16:00:00Z, the requested deadline is 2026-10-25T16:00:00Z. It does not add two days to the current deadline or start a new two-day period now.

• A repeated or smaller request returns the existing deadline successfully if it is still in the future. An extension never shortens the deadline, and retries do not accumulate extra time.
• An expired context can be renewed if the requested deadline is in the future. Otherwise the response is HTTP 410 OE_CONTEXT_EXPIRED.
• A context without an explicit deadline stays unchanged and returns ExpiresAtUtc: null. The request must still contain a valid ExpireAfterSec.
• Cancellation is permanent. A canceled context returns HTTP 410 OE_CONTEXT_CANCELLED and cannot be extended.

{
    "ContextId": "uYZkEP0g22nPZwtCj6ASWef9Lpmh81Ahs1mnAdw4Z7PlDFbOK6",
    "ExpiresAtUtc": "2026-10-25T16:00:00Z"
}

The context ID, both processing URLs, prediction history, and other settings stay the same. The client can continue using its existing URL after a successful renewal. Extension does not reset rate limits, account usage, or the original creation time. It cannot extend the lifetime beyond 14 days from creation or postpone cleanup.

Cancel a Context¶

If you want to close a context early, call this endpoint from your server or LAN client. Replace {id} with ContextId. No API key or request body is required.

POST https://gadget-pv1-oeapi.octoeverywhere.com/api/gadget/v1/cancelcontext/{id}

{
    "ContextId": "uYZkEP0g22nPZwtCj6ASWef9Lpmh81Ahs1mnAdw4Z7PlDFbOK6",
    "IsCancelled": true
}

Cancellation is permanent. Repeating the request returns the same successful result, so it is safe to retry. You can also cancel an expired context or one whose account is blocked by billing. The context information remains readable until normal cleanup.

Stop scheduling images as soon as you cancel. Other processing servers can take up to five seconds to observe the cancellation. Inspections already admitted or running may finish, and successful inspections are still metered. Cancellation does not abort that work.

Expiration, Cleanup, and Errors¶

ExpiresAtUtc controls when processing stops. A null value means no explicit deadline was configured; it does not mean the context is permanent. Contexts are cleaned up automatically after 14 days from creation, regardless of whether they expired or were canceled. Cleanup is asynchronous, so an expired context may remain readable for a while.

After cleanup, information, cancellation, extension, and processing requests return HTTP 404 OE_CONTEXT_NOT_FOUND. Extension does not restore a removed context. A new print needs a new context.

Stop processing on HTTP 410 OE_CONTEXT_EXPIRED or OE_CONTEXT_CANCELLED. For a continuing print, your server can deliberately renew an expired context before the client resumes. A canceled context cannot be reopened. Do not automatically create another context to bypass either state.

All endpoints use the common JSON error response. See Error Handling for invalid requests, account restrictions, rate limits, and retry behavior. Use ErrorType for client decisions; the human-readable ErrorDetails text can change.