1. Discover supported sources and outputs
pcbx.tools converts supported PCB layouts, manufacturing packages and electrical text files. The HTTP API is free to use and requires no account or API key. Use it from a server-side agent or script; cross-origin browser access is not enabled.
Read capabilities.json for source families, output formats, route status and input limits. A route marked conversion is conditional on the uploaded contents. Historical formats remain inputs; retired exports are not admitted. Unavailable means that the shared-engine route is awaiting migration. Read output-profiles.json for shared EDA42 output choices. Add your own unique requestId to each selected choice.request.
A catalog entry is not proof that a file is convertible. healthz reports service readiness, queue state and shared EDA42 executable availability. It does not qualify individual profiles or check auxiliary CAD engines. Inspect each eventual output result.
curl --fail-with-body 'https://pcbx.tools/capabilities.json'
curl --fail-with-body 'https://pcbx.tools/output-profiles.json'2. Upload files and select outputs
POST /jobs with multipart/form-data and Accept: application/json. Send one or more files fields, preferably a ZIP preserving the complete project or manufacturing layer set. Send outputs as one JSON text field containing explicit requests. Use unique requestId values to match results to your requests. Select convert operations from the shared EDA42 catalog; historical operations are retained for old job records and receive unsupported results in the new engine path.
Alternatively, send repeated targets fields for default output selection. Do not mix targets with outputs. The optional paths field is a JSON array of safe relative filenames, one per uploaded file. Uploaded files are binary multipart parts, not base64 JSON or remote URLs. Let your HTTP library set the multipart boundary.
Limits: 500 files, 64 MiB per file, 200 MiB total, archive nesting depth 8, and 64 explicit output requests. Expanded archive contents are also checked.
A JSON submission returns 202 Accepted with a private job URL, statusUrl, expiry and initial state. Save the response immediately. Without Accept: application/json, the web form flow returns a 303 redirect. There is no idempotency-key contract: do not automatically repeat a POST after a timeout or lost response. requestId identifies an output within a job and does not deduplicate submissions.
curl --fail-with-body --max-time 120 \
-H 'Accept: application/json' \
-F 'files=@board.kicad_pcb' \
-F 'outputs=[{"requestId":"editor","target":"eda42","operation":"convert"}]' \
'https://pcbx.tools/jobs' > job.json3. Poll until the job finishes
Resolve statusUrl against the API origin and GET it with Accept: application/json. While state is queued, running or cancelling, wait at least the Retry-After interval (normally two seconds) before polling again. Use an overall timeout. The terminal states are completed, failed, cancelled and timed-out. cancelling acknowledges a cancellation request; it does not confirm worker cleanup. cancelled and timed-out jobs do not offer downloads. A failed job may still have reports or earlier output results worth inspecting.
Progress fields are optional. Display progressPercent only when determinate is true and a percentage is supplied. sequence orders durable progress events; queuePosition may change without a new sequence. A legacy job or unavailable progress ledger can omit sequence and percentage while still returning an authoritative job state.
completed means processing has finished. It does not mean that every requested conversion succeeded. For each result inspect requestId, outputKey, status, fidelity, gaps, checks and outputResolution when present. partial, unsupported or unverified results must not be presented as a fully validated CAD conversion. Download availability alone is not evidence of fabrication or editing correctness.
# With jq installed; job.json is the saved submission response.
status_path=$(jq -er '.statusUrl' job.json)
curl --fail-with-body -H 'Accept: application/json' \
"https://pcbx.tools$status_path" > status.json4. Download the files and conversion reports
Use only URLs returned in the job response: results[].downloadUrl for one output, downloadUrl for the combined ZIP, and reportsUrl for diagnostics. Explicit requests use /jobs/{id}/outputs/{outputKey}/package.zip. Default target requests use /jobs/{id}/{target}/package.zip. Resolve relative URLs against the same API origin and reject unexpected origins or paths in clients.
A missing downloadUrl means that no package is offered for that selection. HEAD can check availability without downloading a ZIP, but may omit Content-Length. Review reports even when an output file exists. Open CAD results in the destination tool and compare the relevant geometry or electrical facts.
Errors, retries and deletion
Send Accept: application/json on all API requests, including downloads, to receive errors as {"error":{"code":"...","message":"..."}}. Success downloads still use application/zip. HTTP 400 means invalid fields or a missing output; 403 means an invalid browser Origin; 404 means an unknown or removed resource; 405 means a disallowed method; 410 means an expired job; 413 means a size limit; 415 means the upload was not multipart.
HTTP 409 means the job is pending or busy, or a file changed during a read. HTTP 503 carries Retry-After: 10 for temporary intake, queue, archive or shutdown conditions. Back off on safe reads, cap retries and preserve the existing job URL. A failed worker can be reported through a 200 status response with state failed, rather than an HTTP error.
DELETE the returned job URL to remove a job and its associated stored files. For running or cancelling work, 202 returns {"url":"...","statusUrl":"..."}, Location and Retry-After: 2 after accepting cancellation. Keep polling statusUrl; 202 does not mean cleanup has completed or files have been deleted. DELETE of queued or finished work, including a cancelled job, returns 204 with no body after deletion. An active download or shared cache operation can return 409. Later requests can return 404. Only delete when the user has authorized removal.
Run the standalone Node.js example
Download and inspect the example client, then run it with Node.js 22 or newer. It uses only built-in libraries, writes into a new local directory and saves a private receipt before polling. It downloads available ZIPs and reports without extracting them or deleting the remote job.
Exit code 0 requires all outputs to succeed with verified fidelity and passed checks. Exit code 2 signals results that need review, including partial, unsupported or unverified outputs; exit code 1 signals a failure, cancellation or timeout. Cancelled and timed-out jobs retain final.json but do not trigger downloads. Read final.json even when ZIP files were downloaded. For exact requests, use --outputs requests.json instead of --to.
If polling or downloading is interrupted, resume from receipt.json into another new directory before expiresAt. Resume does not upload files again. Keep receipts private. If the initial POST response was lost and no receipt exists, acceptance is unknown; the client does not retry the upload.
curl --fail-with-body 'https://pcbx.tools/examples/agent-convert.mjs' -o agent-convert.mjs
# Inspect agent-convert.mjs before running it.
node agent-convert.mjs --origin 'https://pcbx.tools' --to eda42 --out ./converted board.kicad_pcb
# Resume only if the previous run was interrupted:
node agent-convert.mjs --origin 'https://pcbx.tools' --resume ./converted/receipt.json --out ./recoveredPrivate files and responsible automation
The job URL is an access credential: anyone holding it can read, download or request deletion of the job. Keep it out of public prompts, issue trackers, analytics and shared logs. Upload only files the user has authorized you to send to this service.
Job access expires seven days after submission; use the returned expiresAt as the deadline and download needed results beforehand. Identical uploads may reuse cached conversion data, with separate retention described in the privacy notice. Job responses are no-store and noindex, but those headers are not authentication.
An agent should preserve conversion warnings in its answer and distinguish original-file copies, partial recovery and generated output. Gerber artwork cannot supply an absent authored schematic; PDF is output only. Consult the source guides and the per-output report for the actual scope.