---
title: 'API quickstart: upload, check, quote'
summary: The calls that take a board file to a file check report, a price and an order, with curl and the JavaScript client, plus the errors you will meet.
category: ai
audience: agents
order: 3
updated: 2026-11-17
---

## Before you start

Upload, file check and quote work without an account, through a guest session. An order needs an account: see "From a quote to an order" below. The API is at the site's own address under `/api`. Set it once:

```sh
API=https://uliketechnology.com/api
F=board.zip
```

`board.zip` is a flat zip of your Gerber and drill files. For what goes in it, see [Files for fabrication and assembly](https://uliketechnology.com/learn/files-for-fabrication-and-assembly). The examples need `curl` and `jq`.

Every request to the API after the guest session takes `Authorization: Bearer <token>`. An API key goes in the same header in place of the guest token. Every error has the same shape:

```json
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": {}, "requestId": "…" } }
```

Branch on `code`. The `message` is for developers.

Drawing: Five small pictures in order: a key, a file going to an upload address, an hourglass, a report page with findings, and a price tag

1. **Guest session:** the token is shown once.
2. **Upload:** `PUT` the zip to the address the API names, with the headers it names.
3. **Complete,** then poll until the analysis is done.
4. **The report:** findings, which checks ran and which did not.
5. **The quote preview.**

## The flow with curl

Read what can be ordered. This needs no token:

```sh
curl -s $API/v1/capabilities | jq '.options[].id'
```

Open a guest session. The token is shown once and lasts 30 days:

```sh
T=$(curl -s -X POST $API/v1/guest-sessions | jq -r .token)
```

Announce the file. The answer has `uploadId`, `designId`, `uploadUrl` and `requiredHeaders`:

```sh
J=$(curl -s -X POST $API/v1/uploads -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d "{\"fileName\":\"board.zip\",\"sizeBytes\":$(stat -c %s $F),\"sha256\":\"$(sha256sum $F | cut -d' ' -f1)\",\"purpose\":\"design\"}")
```

Send the file to the address the answer names, with every header in `requiredHeaders` (content type, length and checksum; without them the upload is refused with 403). Then complete the upload:

```sh
curl -s -X PUT --data-binary @$F \
  $(echo $J | jq -r '.requiredHeaders | to_entries[] | "-H \(.key):\(.value)"') \
  "$(echo $J | jq -r .uploadUrl)"
curl -s -X POST $API/v1/uploads/$(echo $J | jq -r .uploadId)/complete -H "authorization: Bearer $T" | jq .design.status
```

The status is `analysing` at first. Read the design until it changes. When it is `ready`, the report is in the answer:

```sh
D=$(echo $J | jq -r .designId)
curl -s $API/v1/designs/$D -H "authorization: Bearer $T" | jq '.design.status, .report.headline, .report.counts'
```

The headline is `no_problems_in_checks_run`, `problems_found` or `could_not_check`. Read `checksRun` and `checksNotRun` too: a check that did not run is not a pass. The other statuses are `needs_mapping` (set the layers with `PUT /v1/designs/{designId}/layer-mapping`), `needs_engineer` and `rejected`.

Ask for a price preview. `selection` and `destinationCountry` are required; an empty `selection` takes the defaults:

```sh
curl -s -X POST $API/v1/quote-previews -H "authorization: Bearer $T" -H 'content-type: application/json' \
  -d "{\"designId\":\"$D\",\"quantities\":{\"boardsFabricated\":10,\"boardsAssembled\":0},\"selection\":{},\"destinationCountry\":\"DE\"}" \
  | jq '.mode, .reviewReasons, .totalMinor'
```

`mode` is `instant` (the price stands as shown) or `review` (an engineer confirms it); `reviewReasons` says why. `totalMinor` is in minor units of the answer's `currency`, and is absent when an engineer has to price the job. To keep a quote, `POST /v1/quotes` takes the same body.

## The same flow with the JavaScript client

The `@ulike/sdk` client wraps these routes. It is the client of our own site and is not a public package; this is its shape, so that you can write the same calls with `fetch`. Method names:

```js
import { createClient } from '@ulike/sdk';

let token;
const api = createClient({ baseUrl: 'https://uliketechnology.com/api', token: () => token });

const caps = await api.capabilities();
token = (await api.createGuestSession()).token;
const started = await api.uploadDesign({ name: 'board.zip', bytes }); // announce, PUT, complete
const view = await api.waitForDesign(started.design.id); // polls getDesign
const preview = await api.previewQuote({
  designId: view.design.id,
  quantities: { boardsFabricated: 10, boardsAssembled: 0 },
  selection: {},
  destinationCountry: 'DE',
});
```

Among the other methods are `createUpload`, `completeUpload`, `getDesign`, `setLayerMapping`, `validateDesign`, `getValidation`, `waitForValidation`, `createQuote`, `getQuote`, `reviseQuote`, `listAddresses`, `placeOrder`, `getOrder`, `listOrders` and `cancelOrder`. Errors are thrown as `ApiClientError` with a `status` and a `code`.

## The check for an order

The report you get after upload is made on the files alone. To check the files against an order, call `POST /v1/designs/{designId}/validations` (`validateDesign`) with `order` holding `quantities` and `selection`. The answer is a state: `running`, `failed` or `done`. While `running`, read `GET /v1/validations/{reportId}` (`getValidation`) every second or two until it is `done`.

Drawing: A loop of three steps: upload the files, read the report, fix and upload again; an arrow leaves the loop to a tick when the files are clean

1. **Upload** the zip.
2. **Read the report.**
3. **Fix and upload as a new design.** Stop and ask the person when a fix changes the function, the price or the delivery time.
4. **Clean files:** run the check for the order.

A quote or preview with options that bring other limits (thicker copper, another thickness) needs a check for that selection. If none exists, one is started, and the preview carries the review reason `file_check_pending` and a `check` with its `reportId`. The price is shown at once, but the quote stays in `review` until that check is done. Read the check as above, then ask for the preview again.

## Errors you will meet

| Code                     | Status | What it means                                                                                                                                | What to do                                                                                               |
| ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `DESIGN_NOT_READY`       | 422    | The design is still being read (`details.status` says which state), or has no report yet.                                                    | Read the design until the status is not `analysing`, then ask again.                                     |
| `VALIDATION_FAILED`      | 400    | The request does not have the expected shape, or names an option or value the catalog does not have. `details` lists the issues or problems. | Fix the field named in `details` and send again. Take option ids and values from `GET /v1/capabilities`. |
| `NOT_MANUFACTURABLE`     | 422    | The selection is something we do not make. `details.because` carries the reasons.                                                            | Change the selection; do not retry the same one. Ask the person if the change would alter the board.     |
| `ANONYMOUS_BUDGET_SPENT` | 429    | The daily allowance without an account is used up. `details.resetsOn` is the date.                                                           | Stop. Tell the person; they can sign in or wait until that date.                                         |
| `REVISION_CONFLICT`      | 409    | A revision named a base that is no longer the head of the quote. `details` carries both heads.                                               | Read the head with `GET /v1/quotes/{quoteId}`, reapply your change on it, and send again.                |

Also possible are `DESIGN_REJECTED` (the upload was refused; see `details.reason`), `UNAUTHENTICATED` for a missing or wrong token (a wrong token is refused even on public routes), `FORBIDDEN` for a key or a guest token that may not call the route, and `FEATURE_DISABLED` for a route that is switched off.

## The daily allowance without an account

A guest session has a daily allowance of compute. Uploads and started checks cost more than a plain read, and opening many guest sessions from one network address is also counted. A check that the site starts on its own for a new selection is charged to the same allowance. When it is spent, you get `ANONYMOUS_BUDGET_SPENT` with the date it resets. Signed-in callers are not counted this way.

## From a quote to an order

An order is placed from a kept quote that belongs to an account. A guest token is refused on the order routes. A program works for an account in one of two ways, both described on [For developers and assistants](https://uliketechnology.com/developers):

- **An API key.** The person makes it in their account under API keys and chooses what it may do. Send it as `Authorization: Bearer ulk_…`. A quote that is created with the key belongs to the account. A test key (`ulk_test_…`) works on sample data only.
- **Sign-in for programs.** An assistant registers itself, the person sees what it asks to do on a page of the site and presses Allow, and the assistant gets a token that is limited to those permissions.

Read the saved addresses with `GET /v1/addresses`. An address is added or changed by the person in the browser. The shipping address must be in the quote's `destinationCountry`.

Place the order with `POST /v1/orders`. The route needs an `Idempotency-Key` header: one new key of 8 to 80 visible characters per intended order, and the same key again when you retry:

```sh
curl -s -X POST $API/v1/orders -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -H "idempotency-key: $(uuidgen)" \
  -d "{\"quoteId\":\"$Q\",\"expectedTotalMinor\":$TOTAL,\"shipToAddressId\":\"$SHIP\",\"billToAddressId\":\"$BILL\",\"paymentMethod\":\"bank_transfer\",\"termsVersion\":\"$TERMS\",\"dangerousGoods\":false}"
```

`expectedTotalMinor` is the quote's `totalMinor` that the person agreed to. `termsVersion` names the version of the terms of sale that the person accepted. `dangerousGoods` says whether the shipment holds batteries or other dangerous goods.

Nothing is placed by this call. The answer is `APPROVAL_REQUIRED` (422) with `details.approvalUrl`, for an API key and for the token of an assistant that signed in alike. Give that link to the person. They open it, sign in, see the order and the total, and approve or decline. The link works once, runs out after 24 hours, and stops working if the quote or the total changes.

After the approval the order exists: list the account's orders with `GET /v1/orders` and read one with `GET /v1/orders/{orderId}`. It carries `order.number`, the pro-forma invoice number in `proFormaNumber`, the account to pay into in `sellerBank` and, under `payments`, the `bankReference` to write on the transfer.

Payment is by bank transfer, made by the person. No key and no assistant can pay. Follow the order with `GET /v1/orders/{orderId}`. An engineer confirms every order before production.

| Code                | Status | What it means                                                                                      | What to do                                                               |
| ------------------- | ------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `APPROVAL_REQUIRED` | 422    | A signed-in person has to approve first. `details.approvalUrl` is the page.                        | Give the link to the person. Do not look for a way round it.             |
| `TOTAL_MISMATCH`    | 422    | `expectedTotalMinor` is not the quote's total. `details.totalMinor` is the total.                  | Read the quote again and show the person the price before you ask again. |
| `QUOTE_EXPIRED`     | 410    | The quote is past its validity.                                                                    | Revise the quote for a new price, and show it to the person.             |
| `CONFLICT`          | 409    | `details.reason` is `quote_ordered` or `quote_not_priced` (an engineer has to give a price first). | Do not retry. Tell the person.                                           |
| `INTAKE_CLOSED`     | 503    | No orders are taken at the moment. `details.reopensOn` is the date, when there is one.             | Stop. Tell the person.                                                   |

The same service is offered to assistants as named tools through an MCP server: see [What MCP is and how agents order](https://uliketechnology.com/learn/what-mcp-is-and-how-agents-order).
