sailing Foudra MRP
Reference manual chevron_rightapi/index

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:

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.

  1. 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.
  2. On Allow, the browser comes back to redirect_uri?code=…&state=…; on Deny, ?error=access_denied. A code lasts 10 minutes and works once.
  3. POST https://foudra.com/oauth/token, form-encoded, client authentication by HTTP Basic (a public client sends client_id in 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".

  1. 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.
  2. POST https://foudra.com/oauth/revoke with token=… (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.