API Documentation

Programmatic access to your Artifact resources. All endpoints require an API key passed via the Authorization header.

Authentication

Enter your API key to test endpoints directly from this page:
If you do not have an API key, you can create one in the User Dropdown API Keys & Documentation Modal.

Quick Start

Get from zero to a full BOM export in four API calls. Navigate the hierarchy: Projects → Diagrams → Versions → Export.

List your projects

GET /api/v1/projects/list

List diagrams in a project

GET /api/v1/diagrams/list?projectId=PROJECT_ID

List versions of a diagram

GET /api/v1/diagram-versions/list?diagramId=DIAGRAM_ID

Export the BOM

GET /api/v1/diagram-versions/bom/csv?diagramVersionId=VERSION_ID

Finding IDs from the UI

You can also find the projectID, diagramID, and diagramVersionID directly from the app. Open the Version History for any diagram, then click the gear icon (⚙) on any version row and select Copy API Info. This copies a JSON object with all three IDs to your clipboard.

Resource Hierarchy

All resources are scoped to your organization via your API key. IDs are UUIDs. Timestamps are ISO 8601.

Organization (scoped by API key)
├── Projects
│   └── Diagrams
│       └── Diagram Versions (drafts & releases)
│           ├── Exports: BOM, Connections Table, Netlist
│           └── Harnesses
│               └── Exports: BOM, NX PLMXML
└── Library (shared component catalog)
    ├── Devices     ├── Connectors    ├── Cables
    ├── Accessories ├── Tools         └── Design Blocks

Endpoints

GET

/api/v1/projects/list

List Projects

GET

/api/v1/diagrams/list

List Diagrams

GET

/api/v1/diagram-versions/list

List Diagram Versions

GET

/api/v1/diagram-versions/raw

Get Diagram Version Raw Data

GET

/api/v1/diagram-versions/bom/raw

Get Diagram Version BOM Table Raw

GET

/api/v1/diagram-versions/bom/csv

Get Diagram Version BOM Table CSV

GET

/api/v1/diagram-versions/connections-table/raw

Get Diagram Version Connections Table Raw

GET

/api/v1/diagram-versions/connections-table/csv

Get Diagram Version Connections Table CSV

GET

/api/v1/diagram-versions/netlist/raw

Get Diagram Version Netlist Raw

GET

/api/v1/diagram-versions/netlist/csv

Get Diagram Version Netlist CSV

GET

/api/v1/harnesses/list

List Harnesses

GET

/api/v1/harnesses/raw

Get Harness Raw Data

GET

/api/v1/harnesses/bom/raw

Get Harness BOM Table Raw

GET

/api/v1/harnesses/bom/csv

Get Harness BOM Table CSV

GET

/api/v1/harnesses/plmxml

Get Harness NX PLMXML

GET

/api/v1/library

Get Library

Data Model Reference

When using the /raw endpoints, responses contain the full diagram structure. Here is a reference for the key types.

Node Types

Type	Description	Key Data Fields
deviceNode	ECU, sensor, switch, terminal, or design block	reference_name, part_name, ports[], symbol_name, origin_data
connectorNode	Standalone inline connector	ports[] (single port with pins)
spliceNode	Wire splice point	name, library_item_id
textNode	Text annotation	textProps, backgroundColor, borderColor
annotationNode	Shaped annotation (diamond, circle, etc.)	shape, color, description
imageNode	Embedded image or PDF	imageId, fileName, crop
tableNode	Data table	rows[], columnWidths[]
ghostNode	Unconnected wire endpoint	—
bundledNode	Cable bundle split point	—
arrowNode	Arrow annotation	startCap, endCap, edgeType, label

Edge (Wire) Fields

Field	Type	Description
reference_name	string	Wire identifier (W1, W2, ...)
part_name	string	Wire part name from library
wire_gauge	string	Wire gauge value
wire_gauge_unit	AWG \| MCM	Gauge unit system
insulation	string	Insulation color
length	number	Wire length
length_unit	string	in, ft, cm, m, mm
harness	string	Harness this wire belongs to
library_item_id	string	Reference to cable/wire library item
child_ids	string[]	For cables: IDs of bundled wire edges
accessories	array	Attached accessories (backshells, etc.)
tools	array	Required tooling
procurement_data	object	Purchasing metadata (see below)

Procurement Data

Can appear on library items, ports, pins, and edges. All fields are optional.

Field	Type	Description
internal_part_number	string	Your internal part number
supplier_part_number	string	Supplier's catalog number
manufacturer_part_number	string	Manufacturer's part number
supplier	string	Supplier name
manufacturer	string	Manufacturer name
lead_time	number	Expected lead time
lead_time_unit	string	days, weeks, months
unit_cost	number	Cost per unit
inventory_quantity	number	Quantity in stock
inventory_unit	string	units, meters, feet

Error Handling

All error responses return a JSON body with a single error field:

{ "error": "Description of what went wrong" }

Status Codes

Code	Meaning	Common Causes
200	OK	Successful request
400	Bad Request	Missing/invalid parameter, malformed UUID, invalid unit value
401	Unauthorized	Missing, invalid, or expired API key
404	Not Found	Resource doesn't exist or doesn't belong to your organization
500	Internal Server Error	Unexpected server failure — contact support

Netlist Naming Specification

Each step in a netlist trace is formatted as a dot-separated label built from the node, port, and pin information. The showPinName and showPinFunction parameters control which pin-level segments appear. When both are off, the label stops at the port level and duplicate traces are collapsed.

Label format by node type

Node Type	Both pins on	Pin name only (default)	Both pins off (port level)
Device	ECU.J1.Pin1.SIGNAL	ECU.J1.Pin1	ECU.J1
↳ with mating connector	ECU.X1.Pin1.SIG, ECU.J1.Pin1.SIG	ECU.X1.Pin1, ECU.J1.Pin1	ECU.X1, ECU.J1
Connector	X123.Pin1.SIGNAL	X123.Pin1	X123
Symbol	GND1.Pin1.GND	GND1.Pin1	GND1
Design Block	PowerModule.J1.Pin1.12V	PowerModule.J1.Pin1	PowerModule.J1
↳ with mating connector	PowerModule.X1.Pin1.12V	PowerModule.X1.Pin1	PowerModule.X1
Splice	SP1	SP1	SP1

When a device port has a mating connector, the trace produces two adjacent steps: the first uses the mating connector reference name as the port spec, and the second uses the base port name. This mirrors how both members of a mated inline connector pair appear as separate steps. For design blocks with a mating connector, only the mating connector step appears — the base port is already visible as the first entry of the internal sub-trace.

Design block internal traces

When traceDesignBlocks=true, the trace continues through the internal wiring of each design block. Internal steps are prefixed with the design block diagram name in square brackets, indicating which sub-diagram the step belongs to. For nested design blocks, prefixes stack to show the full hierarchy:

// A trace that enters a design block "PowerModule" and passes through
// its internal components, then exits:
[
  "ECU.X1.Pin1",                                       // top-level device (mating connector)
  "ECU.J1.Pin1",                                       // top-level device (base port)
  "PowerModule.X2.Pin1",                               // design block boundary (mating connector)
  "[Power Distribution] J1.Pin1",                      // sub-trace starts at base port
  "[Power Distribution] Fuse1.Input",                  // inside "Power Distribution" sub-diagram
  "[Power Distribution] Fuse1.Output",
  "[Power Distribution] RelayBlock.X1.Pin1",           // nested design block boundary
  "[Power Distribution] [Relay Module] K1.Coil.Pin1",  // inside nested sub-diagram
  "[Power Distribution] [Relay Module] K1.Coil.Pin2",
  "[Power Distribution] RelayBlock.X2.Pin2",
  "[Power Distribution] J2.Pin3",                      // sub-trace exit at base port
  "PowerModule.X3.Pin3",                               // back at top-level boundary
  "Sensor.X1.SIG",                                     // top-level destination (mating connector)
  "Sensor.Port1.SIG"                                   // top-level destination (base port)
]

The showPinName and showPinFunction options apply uniformly to all steps, including those inside design blocks.