Validate an import and queue it
Alpha
The contract may change without notice, and imports created with it are not guaranteed to remain compatible. Not covered by the deprecation policy.
Sample request
curl -X PUT "https://api.abyssale.com/designs/import/json/$IMPORT_ID" \
-H "x-api-key: $ABYSSALE_API_KEY"Example 200 response
{
"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"status": "QUEUED",
"next_check_after_ms": 2000,
"links": {
"validate": "https://api.abyssale.com/designs/import/json/64238d01-d402-474b-8c2d-fbc957e9d290",
"status": "https://api.abyssale.com/designs/import/json/64238d01-d402-474b-8c2d-fbc957e9d290",
"dashboard": "https://app.abyssale.com/designs/9c2f31a0-8810-4c4b-bbf5-44a02e1f1d2f"
},
"version": "v2026-08-21"
}Example 401 error response
{
"message": "Unauthorized: missing or invalid API key.",
"id": "unauthorized"
}Call this after every entry of uploads[] has been POSTed to S3. The edge API performs a pre-flight HEAD on every expected key. If any are missing, it returns 422 missing_assets with the list of unfulfilled targets.
Behaviour, limits and caveats
On success, the import status transitions to QUEUED and backend processing picks it up. PUT is idempotent on QUEUED rows. PUT on a PROCESSING, DONE, or FAILED row returns 409 template_import_already_processed.
Path parameters
importId string (uuid) required
Import UUID returned by the POST endpoint.
Response 200
Import queued for processing.
id string (uuid) always
status string always
One of "QUEUED".
next_check_after_ms integer | null always
links DesignImportLinks always
Hypermedia links the client should use instead of constructing URLs by hand.
Show child attributes
validate string (uri)
URL to PUT once all uploads[] have been completed.
status string (uri)
URL to GET for polling import status.
dashboard string (uri)
Human-facing link to the result.
More about dashboard
Human-facing link to the result. Not always present.
A workspace template import (target.kind: "workspace_template") carries it from creation, pointing at the Workspace Templates section keyed by import id.
A design import (target.kind: "design", the default) has no destination until it succeeds — the design does not exist before then — so the link is absent until status is DONE, at which point it points at the design itself.
PUT never returns it: at that moment neither target exists yet.
version string
The API version that produced this response, named by release date (vYYYY-MM-DD). Pattern ^v\d{4}-\d{2}-\d{2}$.
More about version
The API version that produced this response, named by release date (vYYYY-MM-DD). Stamped as a top-level field on JSON object bodies, success and error alike, so a client can always tell which contract answered. There is no version-selection parameter — a single version is maintained at a time.
Two kinds of body are not stamped. Array bodies (the listings) carry no envelope. And a body that already has a version key of its own is left alone — which in practice means Banner, whose version is the generated file's integer counter. So GET /banners/{bannerId} and the synchronous generate are the two responses that do not tell you which contract answered.
The value changes when a new version is released. Match the vYYYY-MM-DD shape rather than pinning today's literal, or your client breaks on the next release.
Errors
Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.
| Status | When |
|---|---|
401 | Unauthorized — missing or invalid API key. |
404 | Import not found or does not belong to the caller's company. id: not_found, with one errors entry at path id. |
409 | Import is past the QUEUED state and cannot be re-validated. id: template_import_already_processed, with one errors entry at path status; the reported status is always one of the five public values (WAITING_FOR_VALIDATION, QUEUED, PROCESSING, DONE, FAILED). |
422 | One or more presigned uploads were never completed (missing_assets). Also returned when the presigned upload window has expired before validation, in which case the import is terminal. |
429 | Too Many Requests. |
500 | Internal Server Error — an unexpected error occurred on our side. |