XJDF API Guide

The XJDF layer provides standards-referenced discovery and validation plus separately protected costing and external messaging. Public metadata is not proof of CIP4 certification, legal conformance, production execution or external GA. The platform vocabulary is XJDF 2.2, XJMF and PrintTalk 2.2; legacy JDF/JMF belongs at connector edges.

Core endpoints

Endpoint	Purpose and authority
GET /api/v1/xjdf	Public discovery
GET /api/v1/xjdf/openapi	Public generated metadata
GET /api/v1/xjdf/capabilities	Static product/media/finishing vocabulary; not organization stock or live device availability
POST /api/v1/xjdf/validate	Public basic CIP4 JSON envelope checks
POST /api/v1/costing/calculate-xjdf	Organization-session costing with server-resolved effective L4 authority

Public metadata/validation does not require a Partner API key or mTLS. Its current process-local IP limiter is 30 requests/minute and can return 429 XJDF_RATE_LIMIT_EXCEEDED with Retry-After. This is not a durable per-organization quota.

Costing requires an authenticated organization session; a different body organization is rejected. The server resolves approved/effective L4 cost authority; supplied client context does not grant it. Missing authority returns 409 COSTING_AUTHORITY_REQUIRED; manual-review output is not a customer quote or unattended AutoBid authority.

Authoritative costing needs exact ResourceSet Media/@ID references present in the resolved snapshot. Media labels/grammage never become guessed IDs or prices. The costing request schema uses its own @Version/ProductList representation; it is not interchangeable with the public validator envelope below.

Validation

Send Content-Type: application/json. The validator expects a CIP4 JSON XJDF root:

curl -X POST https://api.nowtoprint.com/api/v1/xjdf/validate \
  -H 'Content-Type: application/json' \
  -d '{"XJDF":{"Version":"2.2","JobID":"example-job"}}'

This is a minimal envelope, not a production job ticket. The current validator checks root, Version and JobID presence and warns about a missing ProductList or non-2.x version; it is not full XSD/JSON-Schema or exhaustive semantic validation. Missing content type returns 415, malformed JSON or invalid content returns 400; valid validation returns 200. Check the response's validation result and issues. Passing validation does not execute a workflow, establish stock, calculate an authorized quote or certify the document.

XJMF and webhook boundary

External XJMF status vocabulary stays separate from internal workflow stages. Inbound callbacks use /api/v1/webhooks/xjmf with X-XJMF-Signature, X-XJMF-Sender and X-XJMF-Timestamp. The sender must exist in server-side XJMF_SENDER_SECRETS; timestamp must be within five minutes.

The signature is bare hex HMAC-SHA256 of the raw body; the timestamp is checked separately. The current replay cache is process-local for ten minutes, not durable exactly-once delivery. A successful callback receipt does not prove the external operation completed in production. These headers differ from Marketplace Standard Webhooks delivery.

Security and operations

• Keep public metadata, costing sessions and sender HMAC authorization separate.
• Preserve immutable resolved snapshot references for production handoff.
• Treat unsupported/uncertain sources and manual-review outcomes as unresolved evidence.
• Reconcile ambiguous delivery or costing outcomes before repeating effects.

Common errors

HTTP	Code or condition	Meaning
400	Invalid JSON/XJDF	Fix the validator envelope and reported issues
401	Authentication required	Costing needs an organization session
403	Organization scope mismatch	Body organization cannot differ from session
409	COSTING_AUTHORITY_REQUIRED	Approved/effective L4 authority is unavailable
409	COSTING_MANUAL_REVIEW_REQUIRED	Result cannot be used for unattended quoting
422	XJDF_COSTING_MEDIA_AUTHORITY_REQUIRED	Exact authoritative media reference is required
429	XJDF_RATE_LIMIT_EXCEEDED	Public metadata/validation limiter exhausted

Related topics