Create Context API¶

A context is Gadget's analysis session for one print. Create one context for each print, then reuse it for every image from that print.

Contexts expire automatically after 14 days. You do not need to delete them.

Tip

There is no charge for calling this API. AI failure detection API usage pricing only applies to the Process API.

Get your API key without setting up billing. Free Usage Only is on by default. See pricing and free usage for details.

HTTP Request¶

Always send Create Context requests to the primary Gadget API host:

HTTP Request

POST https://gadget-pv1-oeapi.octoeverywhere.com/api/gadget/v1/createcontext

Send {} to get started. No settings are required. In this Bash example, replace prod_YOUR_API_KEY with your key:

curl -X POST \
  'https://gadget-pv1-oeapi.octoeverywhere.com/api/gadget/v1/createcontext' \
  -H 'X-API-Key: prod_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Headers¶

Name	Type	Required	Description
`X-API-Key`	string	Yes	Your Gadget API key.

JSON Request Body¶

All fields are optional. Omit them or send null to use their defaults. WarningConfidenceLevel and PauseConfidenceLevel are integers from 1 to 5, defaulting to 3. They control how confident Gadget must be before it suggests a warning or pause. Your app decides how to act on those suggestions.

Lower values make the model more sensitive, which can catch more issues but may increase false positives. Higher values require more confidence, which reduces false positives but may miss smaller failures.

Example Request Body

{
    "WarningConfidenceLevel": 3,
    "PauseConfidenceLevel": 3
}

Name	Type	Default	Description
`WarningConfidenceLevel`	int	3	Optional. `1` suggests a warning sooner; `5` requires higher confidence before suggesting a warning.
`PauseConfidenceLevel`	int	3	Optional. `1` suggests a pause sooner; `5` requires higher confidence before suggesting a pause.

Optional ExpireAfterSec, MaxProcessCountPerMinute, and ReferenceId fields let you set a deadline, limit the processing rate, or attach your own reference. See Context Management for their limits and behavior. You can leave all three out.

Successful Response¶

The response contains the context ID and two complete URLs for the Process API. Both URLs already include the context ID. Use them as returned; do not rebuild the URL or append the ID. Keep the ID and URLs private: they allow processing without your API key.

Example 200 Response

{
    "ContextId": "uYZkEP0g22nPZwtCj6ASWef9Lpmh81Ahs1mnAdw4Z7PlDFbOK6",
    "ProcessRequestUrl": "https://gadget-regional-subdomain.octoeverywhere.com/api/gadget/v1/process/uYZkEP0g22nPZwtCj6ASWef9Lpmh81Ahs1mnAdw4Z7PlDFbOK6",
    "FallbackProcessRequestUrl": "https://gadget-pv1-oeapi.octoeverywhere.com/api/gadget/v1/process/uYZkEP0g22nPZwtCj6ASWef9Lpmh81Ahs1mnAdw4Z7PlDFbOK6",
    "ExpiresAtUtc": null,
    "MaxProcessCountPerMinute": null,
    "ReferenceId": null
}

Name	Type	Description
`ContextId`	string	The ID of the new context.
`ProcessRequestUrl`	string	The complete primary URL. Start sending snapshots for this print here.
`FallbackProcessRequestUrl`	string	The complete fallback URL. See retries and fallback URLs for when to use it.
`ExpiresAtUtc`	UTC timestamp or null	The processing deadline, or `null` if none was set. Normal 14-day cleanup still applies.
`MaxProcessCountPerMinute`	int or null	The optional per-minute limit, or `null` if none was set.
`ReferenceId`	string or null	Your supplied reference, or `null` if none was set.

Error Response¶

API failures return a non-200 HTTP status with the common JSON error object.

Example Error Response

{
    "ErrorType": "OE_ARGS_PARSE_FAILED",
    "ErrorDetails": "The request body could not be parsed."
}

Name	Type	Description
`ErrorType`	string	A well-known error type. See Error Handling.
`ErrorDetails`	string	Details about this specific error.

For recovery steps, including OE_API_KEY_IP_RESTRICTED, see Error Handling.

Next Step¶

Send a JPEG snapshot to the Process API using the returned ProcessRequestUrl, then follow its inspection timing guidance for the next image.