Using the Artifact API

What you'll learn

• What the Artifact REST API provides and how it relates to the in-app exports from Tutorial 9: BOMs & Exports
• How to get an API key and open the interactive docs at /api/v1/docs
• The resource hierarchy you walk when pulling data (organization → project → diagram → version → harness)
• How to export BOMs, Connections Tables, netlists, harness data, and library inventory programmatically
• How errors, permissions, and v1 limitations behave

Prerequisites

• Complete Tutorial 9: BOMs & Exports so you know what a BOM, Connections Table, and netlist represent in Artifact.
• Complete Tutorial 14: Admin Options — you need Allow User API Access enabled for your role (or be an Administrator who can turn it on), and you must create an API key from API Keys & Documentation in your profile menu.

Steps

1Understand what the API is for

The Artifact API is a read-only programmatic surface for data you already manage in the app. Version v1 exposes GET endpoints only — you can list resources and download exports, but you cannot create diagrams, edit library parts, or release versions through the API today.

Every request is scoped to your organization and inherits your user permissions. An Editor's key can read the same projects and diagrams they can open in the UI; a Viewer's key is read-only in the same way.

Typical uses:

• Nightly BOM or Connections Table pulls into ERP/MRP
• Custom dashboards over library procurement fields
• Harness or diagram JSON fed into downstream CAD or analysis tools
• Netlist export for test-bench or simulation workflows

What the API does not cover in v1: PDF/PNG drawing export, Cut Lists, diagram edits, or library writes.

2Confirm you have access and create a key

API access is opt-in per organization.

1. An Administrator opens Admin Controls (bottom-left profile avatar → Admin Controls) and sets Allow User API Access to Admin, Editor, or Disable API Access (Tutorial 14: Admin Options, Step 5).
2. If your role is allowed, click your profile avatar in the bottom-left corner → API Keys & Documentation.
3. Click Create New API Key, set a Key Name (minimum 10 characters) and Expires In (7–365 days), then Create Key.
4. Copy the key immediately — it is shown once. Store it in a secrets manager, not in source control.

Keys inherit your permission level. If an admin later disables API access for your role, existing keys below that threshold stop working.

Screenshot

3Open the API documentation

The in-app docs are the source of truth for paths, parameters, and live testing.

1. In the API Keys modal, click View API Documentation (opens /api/v1/docs in a new tab), or browse directly to {your-artifact-url}/api/v1/docs.
2. Paste your API key into the Authentication field at the top. A green check confirms it is loaded for Try it buttons on each endpoint.
3. Expand any endpoint to see required headers/query params, example responses, generated curl commands, and a Send Request tester.

Screenshot

4Authenticate every request

Pass the key as a Bearer token:

Authorization: Bearer <YOUR_API_KEY>

Use your deployment's base URL — for Artifact Cloud that is typically https://app.artifact.engineer (self-hosted instances use their own hostname). All v1 routes live under /api/v1/.

Example:

curl -X GET "https://app.artifact.engineer/api/v1/projects/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

Most endpoints accept parameters as query strings (recommended) or as custom headers with the same names.

5Walk the resource hierarchy

You usually discover IDs top-down before exporting a specific version:

Organization (implicit — scoped by your API key)
└── Projects          GET /api/v1/projects/list
    └── Diagrams      GET /api/v1/diagrams/list?projectId=…
        └── Versions  GET /api/v1/diagram-versions/list?diagramId=…
            ├── BOM / Connections Table / Netlist / raw JSON
            └── Harnesses   GET /api/v1/harnesses/list?diagramVersionId=…
                └── Harness BOM / raw layout
└── Library           GET /api/v1/library

All IDs are UUIDs. Pick the diagram version you want — often a release for manufacturing, or the latest draft for work-in-progress automation.

6Export a diagram BOM

These endpoints mirror the in-app BOM modal (Tutorial 9: BOMs & Exports) as JSON or CSV.

JSON — structured rows plus a columns array:

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

CSV — same data as a downloadable file:

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

Optional query parameters on both:

Example CSV download:

curl -G "https://app.artifact.engineer/api/v1/diagram-versions/bom/csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "diagramVersionId=VERSION_ID" \
  --data-urlencode "bomType=all" \
  -o bom.csv

7Export a Connections Table or netlist

Connections Table — one row per conductor, same pin-to-pin view as the in-app table:

GET /api/v1/diagram-versions/connections-table/raw?diagramVersionId=…
GET /api/v1/diagram-versions/connections-table/csv?diagramVersionId=…

Netlist — electrical nets with ordered trace steps (see the Naming Specification section in /api/v1/docs):

GET /api/v1/diagram-versions/netlist/raw?diagramVersionId=…
GET /api/v1/diagram-versions/netlist/csv?diagramVersionId=…

Useful netlist query flags:

• traceDesignBlocks=true — continue traces through design-block internals (steps prefixed with [Block Name]).
• showPinName / showPinFunction — control label granularity in each trace step (defaults: pin name on, function off).
• CSV-only: showHarness, showCable, showWire — insert harness/cable/wire columns between trace steps.

8Pull harness data and harness-scoped BOMs

After listing harnesses for a diagram version:

GET /api/v1/harnesses/list?diagramVersionId=VERSION_ID

You can fetch:

• Raw harness layout (ports, segments, treatments) — GET /api/v1/harnesses/raw?harnessId=…
• Harness BOM (JSON or CSV) — GET /api/v1/harnesses/bom/raw?harnessId=… or …/bom/csv?harnessId=…

Harness BOM parameters match the diagram BOM (bomType, unit fields). This is the API equivalent of opening BOM from Harness Properties in the harness editor — treatments and harness-scoped parts roll up here.

There is no Cut List endpoint in v1; cut lengths still require the in-app Cut List modal (Tutorial 9: BOMs & Exports, Step 5).

9Read the full library catalog

Return every library item in your organization:

GET /api/v1/library

Each item includes its data payload (ports, wires, procurement fields, categories, etc.). This complements the Library Dashboard CSV export (Tutorial 10: Library & Project Dashboards Part A) when you want the raw JSON for a custom integration rather than a filtered query result.

10Fetch raw diagram JSON for custom tooling

When you need the complete version payload — every device, wire, preference, and title-block field — rather than a tabular export:

GET /api/v1/diagram-versions/raw?diagramVersionId=VERSION_ID

The response wraps the same diagram-version document the editor persists: nodes, edges, preferences, and pageData. Use this for bespoke parsers, diff tools, or feeding data into scripts that don't map cleanly onto BOM or Connections Table columns.

11Handle errors

Failed requests return JSON like { "error": "…" } with standard HTTP status codes:

If a call succeeds in the docs Try it panel but fails in your script, compare the exact query string and Bearer header first.

Summary

You confirmed API access, created a Bearer token from API Keys & Documentation, and used /api/v1/docs to explore v1's read-only endpoints. You walked the project → diagram → version hierarchy, exported BOMs, Connections Tables, and netlists (JSON or CSV), pulled harness and library data, and know where raw diagram JSON fits. The API mirrors Tutorial 9: BOMs & Exports's manufacturing exports for automation — without PDFs, Cut Lists, or write access.

What's next

• → Tutorial 9: BOMs & Exports — compare API output to what you see in the in-app modals and tune units/filters to match.
• → Tutorial 10: Library & Project Dashboards — project-scale BOM and bulk PDF export still live in the UI, not the REST API.
• → Tutorial 14: Admin Options — rotate keys, revoke access, or adjust Allow User API Access for your team.