Get import status
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 GET "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",
"name": "Holiday Campaign",
"status": "PROCESSING",
"created_at_ts": 1234567890,
"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"
},
"warnings": [
{
"message": "string",
"code": "color_converted",
"path": "layers[2].properties.color",
"layer": "headline"
}
],
"error": {
"path": "string",
"code": "string",
"message": "string"
},
"result": {
"kind": "design",
"uuid": "00000000-0000-0000-0000-000000000000",
"project_uuid": "00000000-0000-0000-0000-000000000000"
},
"version": "v2026-08-21"
}Example 401 error response
{
"message": "Unauthorized: missing or invalid API key.",
"id": "unauthorized"
}Poll the status of a JSON template import. Scoped to the caller's company.
Behaviour, limits and caveats
Returns next_check_after_ms (suggested delay before the next poll, null on terminal states), a stable append-only warnings[] array, and a structured error object when status is FAILED.
Expired upload windows. An import that reaches WAITING_FOR_VALIDATION and is never validated before its presigned upload window closes is reported as terminal: status: "FAILED", next_check_after_ms: null, no validate link, and error: {path: "uploads", code: "missing_assets", ...}. This is derived at read time from the import's creation timestamp — the GET performs no write, so the import keeps its original state. A poller should therefore always drive off terminal states rather than waiting indefinitely.
Path parameters
importId string (uuid) required
Import UUID returned by the POST endpoint.
Response 200
Import found.
id string (uuid) always
name string always
status string always
One of "WAITING_FOR_VALIDATION", "QUEUED", "PROCESSING", "DONE", "FAILED".
created_at_ts integer always
validated_at_ts integer | null always
Unix timestamp when PUT was called. null until validated.
next_check_after_ms integer | null always
Suggested delay before polling again. null on terminal states (DONE, FAILED).
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.
warnings array of Warning always
Stable append-only list of non-fatal backend decisions (font fallback, image scaled down, etc.).
More about warnings
Stable append-only list of non-fatal backend decisions (font fallback, image scaled down, etc.).
Warning codes: font_weight_adjusted, text_fit_failed (non-strict), preview_generation_failed, property_dropped_for_type (a property the design type cannot render — shadow, text_shadow, pattern_name, pattern_color, overlay on print — was accepted and removed from the imported design; one entry per occurrence), print_settings_not_recoverable, animation_duration_derived, color_converted (a solid color was converted into the design type's color space — hex → cmyk on printer, cmyk → hex on static/animated; emitted by the edge at POST time and by as-import), property_not_representable (as-import only — the design stores a property the import schema does not model, so it was omitted from the exported payload).
preview_generation_failed is reported at formats on static/printer/animated; on printer_multipage it names the failing page — one warning per failing page at pages[i] (bare pages when the page index cannot be resolved).
Show child attributes
message string always
Human-readable explanation.
code string
Stable, machine-readable code, when the warning has one. Absent on purely informational entries.
path string
Where in the payload the warning applies, same syntax as Problem.path.
layer string
Name of the layer the entry belongs to, when it was raised while transforming a layer.
More about layer
Name of the layer the entry belongs to, when it was raised while transforming a layer. An index in path identifies a position in the emitted array, which is not the name the caller sees in the editor — group on this rather than parsing path.
error object | null always
The failure, when status is FAILED; null otherwise. Same shape as an entry of the errors[] array — see Problem.
Show child attributes
path string
Where the failure occurred, e.g. layers[3].properties.font_size. When the failure came from a layer, this is how you identify it — there is no separate layer field here, unlike a Warning.
code string
Stable, machine-readable code — branch on this, not on message.
message string
Human-readable explanation.
result object | null always
What the import produced. null until status is DONE, then polymorphic on the requested target.kind: { kind: "workspace_template", uuid } or { kind: "design", uuid, project_uuid }.
Show child attributes
kind string
One of "workspace_template", "design".
uuid string (uuid)
UUID of the created template or design.
project_uuid string (uuid)
Project UUID (present when kind is design).
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. |
429 | Too Many Requests. |
500 | Internal Server Error — an unexpected error occurred on our side. |