The API
JSON over HTTPS on the company's own subdomain, authenticated with an API key as Authorization: Bearer fdr_…. A key's scope limits it: read keys may only GET, write keys may do everything except approve or send a purchase order, approve keys may do those too. Decimals (quantities, money) are strings — JSON numbers are floats and these are not. Errors are {"error": "…"} with a meaningful status.
How to make a key, send it and use the API from Python, with worked examples, is in the developer manual; the OpenAPI description is this list for tools to read.
An application used by many companies (Syncomatic, a phone app) uses OAuth 2.0 instead of a key, so that each user allows it themselves and can disconnect it from Connected apps. See OAuth at the end of this page; its access tokens (fdo_…) are sent the same way as keys and obey the same scopes.
Reading
| Endpoint | Returns |
|---|---|
GET /api/categories |
Every category, unpaged: id, code, name, description, parent_code, default_part_type, is_section (holds categories, so no parts: leave it out of a picker), is_active and parts (how many live parts). ?code=902 finds one, in any case |
GET /api/parts · /api/parts/{id} |
Parts, paged (?page=&per=); ?category=504 narrows to a category, ?q= searches number, name, description, notes, manufacturer and manufacturer's part number; ?manufacturer_part_number= is an exact match in any case, to ask whether a part already exists; a part includes on_hand, manufacturer and manufacturer_part_number |
GET /api/parts/{id}/barcode.png |
The part number as a Code 128 barcode PNG, number printed beneath; ?scale=1–10, ?height= (pixels), ?text=0 for bars only. Each part's JSON gives this path as barcode_url |
GET /api/parts/{id}/bom |
The part's BOM lines: child part, quantity per, reference, routing step |
GET /api/parts/{id}/routing |
The part's routing steps, with totals |
GET /api/parts/{id}/images |
The part's images: id, filename, content type, bytes, SHA-256, primary flag, width and height, and url and thumb_url for the file; with none of its own, its category's, marked from_category |
GET /api/parts/{id}/documents |
The part's documents: id, type, title, revision, filename, content type, bytes, SHA-256, printer_model for G-code (the printer it was sliced for, read from the file), and url for the file |
GET /api/documents/{id} |
A document's file, as uploaded |
GET /api/images/{id} |
An image's file, as uploaded; /api/images/{id}/thumb is its thumbnail |
GET /api/suppliers |
The suppliers; ?code=DIGIKEY narrows to one, in any case |
GET /api/lookup/digikey/{number} |
A part at DigiKey, by DigiKey's number or the manufacturer's (percent-encoded): description, manufacturer, category, specifications, datasheet, and every packaging with its DigiKey number and price breaks, in the company's currency. Foudra asks DigiKey, so your application needs no DigiKey account; answers are reused for a day, and DigiKey's daily limit is shared, so ask once per part |
GET /api/parts/{id}/sourcing |
Who sells the part, as what, for how much |
GET /api/demand?status=open&channel= |
Demand orders with channel, reference, quantity and shipped quantity |
GET /api/channels |
The channels |
GET /api/channels/{code}/listings |
Every part listed on the channel with its channel part number; null means not pushed yet |
GET /api/stock |
One row per part, location and lot (lot_id, lot_code, expires_at; untracked stock has none); ?part_id= for one part's rows |
GET /api/locations?code= |
Stock locations by code (code, name, kind, parent_code); with code, the one a scanned label names, or none |
GET /api/locations/{id} |
A location and what it holds (stock: part, lot, quantity) |
GET /api/locations/{id}/barcode.png |
A location's code as a Code 128 PNG, for its shelf label |
POST /api/locations/{id}/count |
A stock take of the location: the lines whose count differs, each with the figure the sheet showed (expected) and what was found (counted); booked as stocktake movements. Refused whole, with a 409 naming the line and Foudra's figure now, when stock moved since the sheet was drawn. Operator role; send an Idempotency-Key |
GET /api/lots?q= |
Lots and serial numbers, newest first: code, part, on hand, expiry, supplier's batch |
GET /api/lots/{id}/barcode.png |
A lot's or serial's code as a Code 128 PNG, like a part's; barcode_url in each lot's JSON |
GET /api/barcode?v= |
What a scanned label is, and the thing itself, in one call: kind (part, location or lot), url, and data as that URL gives it. P:, L: and T: labels are looked up as that kind only; a bare code as a lot, then a location, then a part number. A lot code several parts share is a 409 listing them |
GET /api/sourcing?supplier=&supplier_part_number=&part_number= |
Which of our parts is a supplier's number, or the reverse. Case-insensitive |
GET /api/purchase-orders?status=&number=PO-00004 |
Orders with supplier, subtotal and a link. number finds one the way people name it |
GET /api/purchase-orders/{id} |
An order with its lines |
GET /api/workstations · /api/workstations/{id} |
Stations with group and status |
GET /api/workstations/{id}/next |
The job this station should do now, with its materials — null unless the station is idle and a step is ready. ?material=<part id> restricts to jobs consuming that part. The response carries the station's current_material and requires_material_change |
GET /api/work-orders?status=&number=WO-00023&external_ref= · /api/work-orders/{id} |
Orders; a single order includes its steps and each step's materials and readiness. Each open order carries the forward schedule's forecast: expected_start, expected_finish, late (finishing after due_at) and delay_reasons; compare expected_finish with due_at to see a slip. Finished and cancelled orders have no forecast (null) |
GET /api/{parts,workstations,work-orders}/{id}/custom |
The opaque JSON, or null |
GET /api/asset-classes |
Each asset class with its meters' keys and its service plans' names and limits: what a script may send |
GET /api/assets?external_ref=&class=&serial=&status= · /api/assets/{id} |
Assets, paged; a single asset adds its meters and where it stands on each service plan (status, each limit's due point and what's left, the governing limit, the open work order) |
GET /api/services-due |
Every active asset's services that are due soon, due or overdue, worst first, as on Services due |
Writing
| Endpoint | Body | Does |
|---|---|---|
POST /api/purchase-orders |
{supplier, currency?, exchange_rate?, expected_at?, external_ref?, notes?, lines:[{supplier_part_number | part_id, quantity, unit_price?}]} |
Creates a draft; lines by their number are resolved through sourcing. An unknown number fails the whole request naming the line. A human approves |
PUT /api/workstations/{id}/status |
{"status": "idle|busy|blocked|offline", "note"?} |
Mirrors a machine's state |
POST /api/work-order-steps/{id}/start |
{"workstation_id"?} |
Takes a step |
POST /api/work-order-steps/{id}/complete |
{"quantity": "9", "consumed"?: [{"part_id", "quantity"}], "used"?: [{"part_id", "lots": ["R-2291"]}], "made"?: ["G0088"], "expires"?: "2027-03-31"} |
Records units made; backflushes materials at BOM standard, or at the reported actual for any part named in consumed; last step receives output. For tracked parts: used names the lots or serial numbers consumed, made the output's serial numbers (one per unit, required) or its lot (default: the order's number), expires a new output lot's expiry |
POST /api/work-order-steps/{id}/scrap |
{"quantity": "9", "consumed"?: […], "used"?: […], "note"?} |
A run that made nothing: materials consumed, no output, the step's count unchanged |
POST /api/work-order-steps/{id}/pause |
A running step with quantity left goes back to pending, progress kept, station released — so the next job is chosen afresh. The print manager does this after every bed | |
PUT /api/workstations/{id}/material |
{"part_id": 934} or {"part_id": null} |
What the station is set up with — a printer's loaded filament |
PUT /api/tasks/{source} |
[{key, priority, message, href, actions?: [{key, label, tone?}]}] |
Replaces this source's task set wholesale; anything omitted is resolved. Source names are lowercase slugs. A task may offer up to six actions — buttons a human can press; pressing one resolves the task with that key as its outcome, which the source reads back. A task with an outcome is never reopened: use a new key for a new occurrence |
GET /api/tasks/{source} |
This source's open tasks and its recently resolved ones with an outcome — how an integration learns which button was pressed |
|
PUT /api/{kind}/{id}/custom |
The JSON itself | Replaces the opaque blob (64 KB max) |
POST /api/parts |
{category_code, name, part_type, description?, notes?, unit_of_measure?, is_stocked?, minimum_stock?, lead_time_days?, tracking?, manufacturer?, manufacturer_part_number?, custom?} |
Creates a part; the stock number is allocated in the category. Returns the part |
POST /api/suppliers |
{code, name, currency?, website?, contact_name?, email?, phone?, lead_time_days?, payment_terms?, notes?} |
Adds a supplier and returns it; currency defaults to the company's. A code already in use is refused (409), so looking a supplier up by code and adding it when missing can't make two |
POST /api/parts/{id}/bom/lines |
{child_part_id, quantity, reference?, notes?, routing_step_id?} |
Adds a BOM line; the cycle rules apply |
PUT /api/bom/lines/{id} |
{quantity?, reference?, notes?} |
Edits a line |
POST /api/parts/{id}/routing/steps |
{name, group_code?, seq?, setup_minutes?, run_minutes_per_unit?, batch_size?, instructions?} |
Adds a routing step; seq blank takes the next ten |
POST /api/parts/{id}/images |
multipart, field file |
Uploads an image (12 MB max); the first becomes primary |
POST /api/parts/{id}/documents |
multipart: file, type (datasheet, technical_data, safety_data, manual, assembly, drawing, certificate, model_3d, gcode, other), title?, revision? |
Uploads a PDF, .docx, Markdown, STL, 3MF or G-code document (20 MB max; Markdown 256 KB; 3D models and G-code 50 MB), inside the company's storage limits |
DELETE /api/documents/{id} |
Deletes a document (204) | |
DELETE /api/images/{id} |
Deletes one of a part's images (204). A category's image is refused (422): every part in the category without its own shows it | |
PUT /api/parts/{id}/sourcing/{supplier} |
{supplier_part_number, unit_price?, currency?, product_url?, minimum_order_qty?, pack_size?, lead_time_days?, is_preferred?, notes?, price_breaks?:[{min_qty, unit_price}]} |
Creates the supplier's row for the part (201) or updates it (200); fields not sent keep their value. A part's first source becomes preferred |
POST /api/demand |
{channel, reference, part_id | part_number | channel_part_number, quantity, due_at?, kind?, notes?} |
Demand received. Idempotent on (channel, reference): a repeat while open updates quantity and date and answers 200; a first arrival answers 201. A closed or cancelled reference is left alone |
POST /api/demand/{id}/ship |
{quantity?, location_id? | location_code?, lots?} |
Demand shipped. Issues that quantity (blank: the rest) from the location, or the part's biggest pile, as a ledger movement referencing the demand; closes the demand once everything has gone. lots names the lots or serial numbers shipped, from wherever they are: required for a serial-tracked product. 409 when there is not enough on hand |
POST /api/demand/{id}/cancel |
Demand cancelled | |
PUT /api/channels/{code}/listings/{part_id} |
{channel_part_number?, is_listed?, notes?} |
Lists a part on the channel, or records the channel's number for it |
To be told when something happens rather than asking, see webhooks.
For an assistant
What a chat agent needs to keep a person on track: one call for "what needs me", lookups by the names people use, and the buttons. Every item carries a url a human can click.
| Endpoint | Returns |
|---|---|
GET /api/brief |
Everything that needs attention now: open tasks, workstation states, draft and open work orders, purchase orders awaiting approval, approved but unsent, and overdue, planned orders due to be firmed, transfers needed, shortages, and jobs the capacity check says will finish late. headline says the same in a few sentences, most urgent first |
GET /api/tasks |
Every open task, most urgent first, with its actions |
GET /api/planning |
The planning page: proposed and firmed planned orders (each says because of what), and each workstation group's schedule with its late jobs |
GET /api/demand/{id}/progress |
"Where is my order?": the demand, the part's stock and inbound supply, the planning run's proposals for this order, the work orders making it, and which of those are scheduled late. Supply belongs to the part, not the order: two orders for one part see the same stock |
Doing things
| Endpoint | Body | Needs | Does |
|---|---|---|---|
POST /api/tasks/{id}/act |
{"action": "ready"} |
operator | Presses one of the task's buttons |
POST /api/tasks/{id}/snooze |
{"days": 2} |
operator | Hides the task; a week when no number is given |
POST /api/tasks/{id}/resolve |
operator | Closes the task by hand | |
POST /api/work-orders |
{part_number | part_id, location, quantity?, external_ref?, due_at?, priority?, notes?, output_location?, release?} |
planner | Raises a work order: a draft, or released when release is true. location is the code of where it draws parts (and puts output, unless output_location differs). external_ref is your name for what the job is about. Send an Idempotency-Key, or a retry raises a second order |
POST /api/work-orders/{id}/issue |
{part_number | part_id, quantity?, note?, lots?} |
operator | Draws a part from stores for the order, outside its BOM; lots names its lots or serial numbers. 409 when there is not enough |
POST /api/parts/{id}/receipts |
{location_code | location_id, quantity, unit_cost?, lot?: {code, expires?, notes?}, supplier_ref?, notes?, purchase_order_line_id?} |
operator | Books stock in at a location, by the code on its label: a bag onto a shelf. A tracked part needs lot, made if new; an untracked part keeps the lot code in the movement's notes. With purchase_order_line_id, receives that line of a sent order at the line's price. Answers with what is now on hand there and in all. Send an Idempotency-Key, or a retry books it twice |
POST /api/work-orders/{id}/release |
planner | Draft to released. Answers with the order and each step's readiness | |
POST /api/work-orders/{id}/cancel |
planner | Cancels an unfinished order | |
POST /api/planning/run |
planner | Runs planning now. Answers with the proposals | |
POST /api/planning/firm |
{"ids": [12, 13], "location": "BHILL"} |
planner | Proposals into draft work orders and purchase orders. location (or location_id) is needed when a make is among them |
POST /api/purchase-orders/{id}/cancel |
planner | Cancels the order | |
POST /api/purchase-orders/{id}/approve |
admin, approve key |
Draft to approved | |
POST /api/purchase-orders/{id}/send |
planner, approve key |
Records the order as sent. Foudra does not transmit it to the supplier | |
POST /api/meter-readings |
{"readings": [{"asset": {"id"} | {"ref"} | {"class", "serial"}, "meter": "nm", "value" | "delta", "read_at"?, "replaced"?, "idempotency_key"?}]} |
operator | Up to 1,000 readings, each standing alone: the answer says of each whether it was recorded, a duplicate (its idempotency_key seen before), history (older than the meter's latest) or refused, and why |
POST /api/assets |
{class | class_id, serial_number, name?, external_ref?, site?, owner?, commissioned_at?, notes?}, or lot_id to commission a serial number in stock |
planner | Adds an asset |
POST /api/assets/{id}/service-events |
{plan | plan_id, performed_at?, notes?} |
operator | Records a service done outside Foudra; the plans it includes are recorded too |
POST /api/assets/{id}/overrides |
{plan | plan_id, meter?, kind: "next_due" | "interval", value | due_at, reason?} |
planner | One asset's own next due point (once) or interval (for good) on one of a plan's limits; meter null is the time limit. Replaces a standing one of the same kind |
DELETE /api/assets/{id}/overrides/{oid} |
planner | Withdraws an override |
Four rules apply to every one of these:
- Who. Send
X-On-Behalf-Of: someone@example.comand the change is made in that user's name, with that user's role. Without it, the key's creator is the actor. Both must hold the role: a key cannot lend its creator's authority to someone else, nor borrow more than its creator has. The header works on the read endpoints too, so the brief is that user's brief. - Preview. Add
?dry_run=1and the request does everything for real and then undoes it. The answer is exactly what would have happened, with"dry_run": true; nothing is changed. Use it before asking a human "shall I?". - Once. Send an
Idempotency-Keyheader (any string up to 200 characters, unique per intended action). A repeat within a week gets the first answer back, with the headerIdempotent-Replay: true, and nothing is done twice. The same key on a different request is refused (422). - Record. Each change writes an audit row naming the key and, when given, who it acted for.
Every answer has summary, a sentence fit to repeat to a human, data, and acted_as. Refusals: 403 for a key's scope or a user's role, 404, 409 when the thing is not in a state that allows it (the message says why), 422 for a bad action or a reused key.
The print-farm shape
Poll /next?material=<loaded> while idle — anything ready in what is loaded? If not, /next unfiltered says what the top job needs; push a change filament task and go blocked. The human fits the spool, sets Loaded material on the workstation page, taps Ready. Then start; print; complete with the quantity and the actual filament used; status idle again. A failed print is scrap, not a completion of zero. The MRP knows nothing about printers.
API writes are recorded against the user who created the key, unless X-On-Behalf-Of names someone else (see above).
OAuth
For an application acting for users of any company. Applications are registered by Foudra (ask through support): you get a client_id, a secret for a server-side application, and your exact redirect URIs are recorded. The flow is the authorization code grant with PKCE (RFC 6749, RFC 7636), and PKCE with S256 is required of every client.
- Send the browser to
https://foudra.com/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=read%20write&state=…&code_challenge=…&code_challenge_method=S256. The user says which company, signs in there and is shown what you asked for. - On Allow, the browser comes back to
redirect_uri?code=…&state=…; on Deny,?error=access_denied. A code lasts 10 minutes and works once. POST https://foudra.com/oauth/token, form-encoded, client authentication by HTTP Basic (a public client sendsclient_idin the form instead):grant_type=authorization_code&code=…&redirect_uri=…&code_verifier=…. The answer:
{"access_token": "fdo_…", "token_type": "Bearer", "expires_in": 3600,
"refresh_token": "fdor_…", "scope": "read write",
"company": {"slug": "acme", "name": "Acme Widgets", "api_base_url": "https://acme.foudra.com"}}
Call the API at api_base_url with Authorization: Bearer fdo_…: the token works only there. An expired or revoked token gets 401 with WWW-Authenticate: Bearer error="invalid_token".
- Refresh before or after the hour with
grant_type=refresh_token&refresh_token=fdor_…. Refresh tokens rotate: each use returns a new one and spends the old. Presenting a spent refresh token is taken as theft and revokes every token from that sign-in; the user must allow you again. So store the new refresh token before using the new access token, and never retry a refresh with the old one. A refresh token unused for 90 days expires. POST https://foudra.com/oauth/revokewithtoken=…(RFC 7009) when the user disconnects on your side. Revoking a refresh token revokes its access tokens too.
Scopes are the API key scopes: read, write, approve, each including the one before. What you get is capped by your registration and by the user's role (viewers and operators read; planners write; admins and owners approve), and the cap is applied again on every request, so a user who is demoted or removed takes your access with them. The token response's scope says what was granted. Writes are attributed to the user, and verbs report "acted_as": {"user": …, "application": …}. X-On-Behalf-Of works as it does with keys.
Errors from the token endpoint are RFC 6749's: {"error": "invalid_grant", "error_description": "…"} with status 400, or invalid_client with 401.