v1 · Stable

SpecMake API

Upload technical documents, fetch structured product data, run compliance checks — all from your own code. REST + JSON, Bearer-token auth. Integrate SpecMake into your existing PIM, ERP, or DPP workflow.

Available on Professional, Enterprise, and Charter Customer plans. Generate keys in your account settings after upgrading.

Authentication

Every request to the API must include your API key in the Authorization header as a Bearer token:

curl https://www.specmake.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_••••••••••"

Keys are shown once at creation and never displayed again. Lost keys must be revoked and replaced. Treat keys like passwords — never commit them to source control, never share them with third parties.

Timeouts & processing time

Async upload + webhook callback is on the v1.1 roadmap. Until then, a synchronous integration is the simplest, most reliable shape.

Conventions

Versioning

Every response includes an X-API-Version: v1 header. Check this header in your client to detect breaking changes — we will bump it (and announce in advance) when v2 ships. The path prefix /api/v1 also stays for the entire v1 lifecycle.

Naming: snake_case vs camelCase

For historical reasons (our internal schema predates v1), the API uses two conventions in the same response:

• Top-level summary fields use snake_case — file_type, source_language, detected_domain, created_at.
• The nested document payload uses camelCase — sourceLanguage, confidenceReason, etc. This mirrors the internal extraction schema.
• document.metadata uses snake_case — the keys come from source-document fields (page_count, domain_detected) and follow source convention.

The same data sometimes appears under both keys (e.g. source_language at the top level and document.sourceLanguage inside the payload). Either is canonical — pick whichever is convenient for your client.

Diagrams

When a saved document has extracted diagrams, each entry in document.diagrams[] carries an imageUrl (1-hour signed URL) plus storagePath, width, height, description, and type. The URL is short- lived; re-fetch the document if you need to ingest images after an hour.

Diagrams are extracted only for documents saved via the web UI (or with save_to_library=true via the API today — planned). A stateless API call with save_to_library=false returns an empty diagrams[].

Cost transparency

Every POST response includes the per-call AI cost in meta.tokens (input/output counts) and meta.estimatedCostCents (USD cents). This is the same value we log to our internal usage table — no markup. Use it to forecast your monthly spend or to budget per-document.

Endpoints

Documents

curl https://www.specmake.com/api/v1/documents \
  -H "Authorization: Bearer sk_live_••••" \
  -F "file=@spec-sheet.pdf" \
  -F "save_to_library=false" \
  -F "run_audit=true"

{
  "id": null,                      // only set when save_to_library=true
  "document": {
    "title": "...",
    "sourceLanguage": "de",        // camelCase inside document
    "metadata": { "domain_detected": "hydraulics_pneumatics", ... },
    "sections": [
      { "heading": "...", "fields": [
        { "key": "...", "value": "...", "unit": "bar",
          "confidence": 0.95, "source": { "page": 2, "quote": "..." } }
      ]}
    ],
    "diagrams": []                 // empty unless save_to_library=true
  },
  "audit": {
    "coverage_score": 87,          // 0-100
    "data_points_extracted": 47,
    "total_data_points_in_source": 54,
    "severity_counts": { "low": 6, "medium": 2 },
    "findings": [ ... ]
  } | null,
  "meta": {
    "fileType": "pdf",
    "fileSize": 230423,
    "fileName": "spec-sheet.pdf",
    "detectedDomain": "hydraulics_pneumatics",
    "processingMs": 31420,
    "tokens": { "input": 10601, "output": 5936 },
    "estimatedCostCents": 15.82    // USD cents, no markup
  }
}

{
  "documents": [
    { "id": "...", "filename": "spec.pdf", "file_type": "pdf",
      "file_size": 230423, "source_language": "de",
      "detected_domain": "hydraulics_pneumatics",
      "status": "completed", "created_at": "2026-05-16T..." },
    ...
  ],
  "has_more": true,
  "next_cursor": "2026-05-15T18:31:00Z"
}

curl https://www.specmake.com/api/v1/documents/abc-123 \
  -H "Authorization: Bearer sk_live_••••"

{
  "id": "abc-123",
  "filename": "spec.pdf",
  "file_type": "pdf",              // snake_case at top level
  "file_size": 230423,
  "source_language": "de",
  "detected_domain": "hydraulics_pneumatics",
  "status": "completed",
  "created_at": "2026-05-16T12:00:00Z",
  "document": {                    // camelCase inside
    "title": "...",
    "sourceLanguage": "de",
    "metadata": { ... },
    "sections": [ ... ],
    "diagrams": [
      { "type": "application_photo",
        "width": 2000, "height": 2000,
        "description": "Figure 1",
        "storagePath": "uuid/0.jpg",
        "imageUrl": "https://...signed...?expires=..." }  // 1h TTL
    ]
  },
  "audit": {
    "coverage_score": 87,
    "data_points_extracted": 47,
    "total_data_points_in_source": 54,
    "severity_counts": { "low": 8, "medium": 6 },
    "findings": [ ... ]
  } | null
}

curl https://www.specmake.com/api/v1/documents/abc-123/translations \
  -H "Authorization: Bearer sk_live_••••"

curl -X DELETE https://www.specmake.com/api/v1/documents/abc-123 \
  -H "Authorization: Bearer sk_live_••••"