Skip to main content
A submission is one extraction job for a URL. You create it, the engine processes it asynchronously, and when it finishes it produces an extraction (referenced by extraction_id) whose output is the design system.

​
Creating submissions

There are two ways to submit work:
  • Single URL: POST /design/submissions with a url.
  • Map mode: POST /design/submissions?map=true treats url as a domain root, discovers the site’s pages, and submits each one as its own extraction. The response shape changes to reflect the multiple URLs discovered. Use max_urls to cap discovery; the server clamps it to 200.

​
Submission options

The single-URL request accepts a few options:
  • force: re-run extraction even when a cached result exists.
  • enable_deep_analysis: run additional, slower analysis steps for a higher-fidelity result.

​
Status and progress

Each submission has a top-level status: accepted, queued, crawling, extracting, completed and failed It also reports a finer-grained current_step as the workflow streams:
Track progress with GET /design/submissions/{id} for a single submission, or GET /design/submissions for a paginated list.

​
Filtering the list

The list is deduplicated by URL and returns the newest submissions first. Narrow it with:
  • status: one lifecycle status.
  • q: free-text search over the source URL (a case-insensitive substring).
  • api_key_id: only submissions created with one API key. Useful for separating environments that share an account.
Alongside the page, total counts everything matching the filter and totals breaks that down into completed, failed, and in_progress. The four in-progress statuses fold into in_progress, so the three buckets sum to total. Both counts ignore pagination, which makes them safe to render as a summary without walking every page. Each item also reports credits_consumed (net of any refund) and api_key_name, so you can attribute spend without a second call.

​
Polling for the result

Extraction is asynchronous, so poll GET /design/submissions/{id}/result:
  • 200: may contain a partial design_system while the workflow runs. Keep polling until status is completed or failed.
  • 409 (NOT_READY): no checkpoint has landed yet. Retry shortly.
  • 404: the submission doesn’t exist or isn’t accessible to the caller.
Read result.design_system once status is completed. See The design system for the structure. The full design system is a large payload. Add ?sections=colors,typography to return only the sections you need, which keeps polling responses small. See Requesting only the sections you need.

​
Downloading the whole extraction

An extraction is more than its design system: it also has the captured HTML and CSS, the screenshot, and every logo, image, and icon the design system references. GET /design/submissions/{id}/download returns a manifest listing all of them as one flat file tree, so you can write the extraction to disk in one pass. Every entry has a relative path and exactly one source:
  • content: inline text to write at that path. This is how guidelines.json (the design system) arrives.
  • url: a file to download to that path, such as crawl/html.html or crawl/screenshot.jpeg.
Assets are mirrored to the engine’s storage before the manifest is built, so the URLs keep working even after the origin site changes. The submission must be completed: an in-progress one returns 409 NOT_READY. Like the result endpoint, authentication is optional, so a public extraction can be downloaded without a key.

​
Caching and freshness

Results are cached and reused across submissions. When a request is served from a previous extraction for the URL, cache_hit is true. To know when the data was actually extracted (its freshness), read completed_at. It is on the submission envelope, on GET /design/submissions/{id}, the /result endpoint, and the list. On a cache hit, completed_at points to the original extraction, not the time you sent the request, so a cached result may have been extracted earlier. On a fresh run, it is the moment the extraction just completed. While a submission is still running, completed_at is null. Set force: true on the request to bypass the cache and run a fresh extraction. That fresh result then becomes the cached result other callers get for the URL.

​
Visibility and sharing

By default a result is private to its owner. Use PATCH /design/submissions/{id}/visibility with { "is_public": true } to make it public. Public results can be read from GET /design/submissions/{id}/result without authentication, which makes extractions shareable. Only the owner can change visibility.