The HTTP API
Everything the web workbench and the CAD app do goes through the server's HTTP API, under
/api/. Your own tools can use it too. Requests and answers are JSON unless a route says
otherwise (document bodies, file uploads and downloads, CSV).
Authentication
- Tools and scripts send an API token:
Authorization: Bearer plm_…. No cookie, no CSRF token. Make one on My account; its scope (full,readorworker) limits what it may do. See Users and permissions. - Browsers sign in with
POST /api/loginand get a session cookie. Every request that changes something must also send the session's CSRF token inX-CSRF-Token; it comes back from/api/loginand/api/me.
GET /api/me answers who you are, your groups, the server's version, the oldest CAD app
it accepts (min_client_version) and the optional features it supports (features:
workspaces, attribute-filters, external-ref, derived-uses; a name is only ever added).
A client that sees derived-uses sends no PUT …/uses after a document; to a server without
it, it publishes the list itself, as before.
Answers and refusals
A refusal is an HTTP status with a sentence meant for a person: 400 for a request that
does not read, 401 when not signed in, 403 for a missing permission, 404 for
something that does not exist, 409 for a conflict with the current state (a released
revision, another user's lock, a duplicate number), 413 for a body over the size limit,
and 429 while the sign-in throttle holds. The CAD app and the web workbench show these
sentences as they are sent.
Every change moves the store's sequence number, and changing answers carry the new
seq. Lists that can be long (/api/parts, /api/bake/jobs) answer a page at a time
with a cursor for the next page.
A part is named by its part number and a revision by its label. Inside a URL, a document key or label with special characters is percent-encoded.
Route families
| Routes | For |
|---|---|
/api/login, /api/logout, /api/me, /api/me/password, /api/logout-all, /api/tokens | signing in, your account and your API tokens |
/api/me/preferences | the CAD app's settings kept for your account |
/api/desktop/link with /poll, /inspect, /approve, /deny; /api/desktop/sign-out; the page /desktop-link | the desktop app's sign-in through your browser (see Connecting the CAD app) |
/api/users, /api/part-types | accounts and part types (administrators) |
/api/parts, /api/parts/:id, …/revisions/:rev with /checkout, /checkin, /state | parts, revisions, check-out and the lifecycle |
…/revisions/:rev/submit, /review, /review/decision, /comments; /api/inbox | review rounds, discussion and the inbox |
/api/workflows, /api/workflow-runs | workflow definitions and runs |
…/revisions/:rev/uses, /bom; /api/parts/:id/bom/diff, /where-used, /replace | structure, BOM, comparison, where-used and Replace everywhere |
/api/categories, /api/bom/…, …/revisions/:rev/attributes, /occurrences | the catalog, BOM layouts, revision and occurrence fields |
/api/manufacturers, /api/suppliers, /api/parts/:id/sourcing | sourcing |
/api/parts/:id/attachments, …/revisions/:rev/attachments, /api/attachments/:id | attachments |
/api/workspaces, /api/workspace/… | workspaces |
/api/parts/:id/family, /generate, /template, /spin-out; /api/bake/… | families, templates and the bake queue |
/api/store/index, /api/store/doc/*key, /api/store/changes | the document store the CAD app reads and writes |
/api/parts/:id/thumbnail | revision thumbnails |
/api/audit, /api/parts/:id/history | the audit log |
/api/settings, /api/scripts | server settings and administrator scripts |
/api/admin/backups, /api/admin/backup, /api/admin/export | backups and exports (administrators) |
/api/setup/… | the setup wizard's library imports (administrators) |
/cad/config | the server describing itself to an installer; no sign-in |
Examples
List the parts in a category (by its id) and every category beneath it, with their attribute values:
curl -H "Authorization: Bearer $PLM_TOKEN" \
"https://plm.example.com/api/parts?category=fasteners&include=attributes&limit=100"
Read an assembly's flat BOM as CSV:
curl -H "Authorization: Bearer $PLM_TOKEN" \
"https://plm.example.com/api/parts/CPART000000042/revisions/B/bom?flat=true&format=csv"
Attribute filters on /api/parts take attr.<key>=<value> (repeat a key for any of
several values), and attr.<key>.min= / .max= for numbers. attr.has_geometry and
attr.has_thumbnail (true or false) find parts with or without 3D geometry or a
current thumbnail.
The document store
The CAD app reads and writes documents through /api/store/:
| Route | Does |
|---|---|
GET /api/store/index | every document's metadata, without the documents |
GET /api/store/doc/*key | read one document |
PUT /api/store/doc/*key | write one; refused unless the revision is in work and you hold its check-out. With If-Match: "<content_hash>" it writes only over that document, and answers 409 (naming when it changed and who holds it) when the revision holds a newer one. An assembly's uses list is set from the document in the same write (feature derived-uses); the answer is {ok, seq, content_hash, size, uses_refused}, where uses_refused says why the list was not derived (the document is written regardless) |
DELETE /api/store/doc/*key | delete one |
GET /api/store/changes?since=<seq> | the current sequence number and which keys moved since seq |
The key is the document key, part/<part number>/rev/<revision>. A document may be up to
the server's document limit (--max-document-mb, default 64 MB).