Authentication and scopes
Send the complete API credential as a Bearer token from trusted server-side code. Never expose it in browser code, URLs, logs, analytics, or an embeddable widget.
| Operation | Required scope |
|---|---|
| Submit Try-On | try_on:create |
| Retrieve Try-On | try_on:read |
| Read usage | usage:read |
Submit an asynchronous Try-On
Send multipart/form-data with an image up to 10 MiB. The full multipart body is limited to 11 MiB. Every submission requires an 8–128 character Idempotency-Key.
curl --request POST \
"$UDUTHIPAAR_BASE_URL/api/v1/try-ons" \
--header "Authorization: Bearer $UDUTHIPAAR_API_KEY" \
--header 'Idempotency-Key: order-4821-try-on-1' \
--form-string 'sessionId=<session-uuid>' \
--form-string 'sessionFabricId=<session-fabric-uuid>' \
--form-string 'consentGranted=true' \
--form-string 'consentVersion=2' \
--form-string 'consentText=Yes, I agree to the Try-On policy.' \
--form 'file=@./customer.png;type=image/png'Safe retry rule
After a timeout, network error, or 503, retry with the same key and exactly the same fields and file. A changed payload with the same key returns 409.
Poll the result
curl "$UDUTHIPAAR_BASE_URL/api/v1/try-ons/$TRY_ON_ID" \
--header "Authorization: Bearer $UDUTHIPAAR_API_KEY"- Poll after 2 seconds, then every 3–5 seconds while HTTP status is 202.
- Stop on 200, 402, 404, or 410.
- Respect the Retry-After header on 429.
- Use the returned image promptly; its signed URL expires in 300 seconds.
Statuses: DRAFT · PHOTO_UPLOADED · QUEUED · PROCESSING · COMPLETED · FAILED · CANCELLED
Read tenant usage
curl "$UDUTHIPAAR_BASE_URL/api/v1/usage" \
--header "Authorization: Bearer $UDUTHIPAAR_API_KEY"The response contains the tenant timezone, current billing period, catalogue and Try-On counts, incurred usage, and daily/monthly budget status.
Error handling
| HTTP | Typical code | Action |
|---|---|---|
| 400 | INVALID_INPUT | Correct the request; do not retry unchanged. |
| 401 | INVALID_API_KEY | Supply or rotate the credential. |
| 402 | BUDGET_EXCEEDED | Ask the administrator to extend the budget. |
| 403 | INSUFFICIENT_SCOPE | Correct API access or scopes. |
| 404 | NOT_FOUND | Verify the ID and credential ownership. |
| 409 | IDEMPOTENCY_CONFLICT | Reuse keys only with identical input. |
| 410 | GONE | Stop retrieving or displaying the result. |
| 413 | BODY_TOO_LARGE | Reduce the request and image size. |
| 429 | RATE_LIMITED | Respect the Retry-After header. |
| 503 | SERVICE_UNAVAILABLE | Retry POST with the same key and input. |
Production readiness
- ✓Store API keys in a managed secret store.
- ✓Use separate sandbox and production keys.
- ✓Grant only the required scopes.
- ✓Persist idempotency keys before submission.
- ✓Store exact consent wording and version.
- ✓Implement polling and Retry-After handling.
- ✓Treat signed image URLs as sensitive.
- ✓Complete UAT certification before enablement.