Technical Documentation

API Reference

A complete reference for the QueueVIO REST API. All endpoints return JSON. Base URL: https://api.queuevio.com

Authentication

All /api/* endpoints require a JWT Bearer token obtained from POST /api/auth/login. Pass it in every request: Authorization: Bearer <token>. The token is scoped to a single tenant — all data is isolated by tenantId automatically.

Authentication Intents Jobs Devices Connectors Events (SSE)

Authentication

/api/auth

Obtain and manage JWT tokens. All other endpoints (except /public/contact) require Bearer token auth.

POST/api/auth/loginObtain a JWT

Request body

{ "email": "you@example.com", "password": "••••••••" }

Response

{ "token": "eyJhbGci...", "tenantId": "ten_01j9x..." }

Intents

/api/intentsAuth required

Submit natural-language job briefs. The AI Intake Service extracts a structured job draft and returns per-field confidence scores. Jobs with confidence ≥ autoApproveThreshold (default 0.80) and no ambiguities are auto-approved and immediately routed.

POST/api/intentsCreate an intent (NL intake)

Parameter	In	Type	Description
nlText*	body	string	Natural-language job brief.
contextHints	body	object	Optional hints — customerId, priority, referenceJobId.

Request body

{
  "nlText": "5,000 A4 CMYK brochures, 130 gsm coated,
             saddle-stitched, needed Friday",
  "contextHints": { "priority": "high" }
}

Response

{
  "id": "int_01j9xk...",
  "status": "auto_approved",
  "confidence": 0.94,
  "jobDraft": {
    "quantity": { "ordered": 5000 },
    "substrate": { "type": "coated", "weightGsm": 130 },
    "colorSpace": "CMYK",
    "finishing": ["saddle_stitch"],
    "status": "routed"
  }
}

GET/api/intentsList all intents

Response

[{ "id": "int_01j9xk...", "status": "pending_review", "confidence": 0.61, ... }]

GET/api/intents/:idGet an intent

Parameter	In	Type	Description
id*	path	uuid	Intent ID.

PATCH/api/intents/:id/approveApprove a pending intent

Approves the AI-extracted job draft as-is. The job is created and immediately enters routing.

Parameter	In	Type	Description
id*	path	uuid	Intent ID.

PATCH/api/intents/:id/rejectReject a pending intent

Parameter	In	Type	Description
id*	path	uuid	Intent ID.
reason	body	string	Optional rejection reason stored in the intent record.

Jobs

/api/jobsAuth required

Create and manage production jobs directly (structured payload, no NL intake). Jobs move through a production chain of stages; each stage is routed to a device by the AI Routing Engine.

POST/api/jobsCreate a job

Request body

{
  "title": "Brochure Run Q3",
  "quantity": { "ordered": 5000 },
  "substrate": { "type": "coated", "weightGsm": 130 },
  "colorSpace": "CMYK",
  "finishing": ["saddle_stitch"],
  "dueDate": "2026-06-27T17:00:00Z"
}

Response

{ "id": "job_01j9xm...", "status": "pending", ... }

GET/api/jobsList all jobs

Parameter	In	Type	Description
status	query	string	Filter by status: pending \| routed \| queued \| in_progress \| completed \| failed.

GET/api/jobs/:idGet a job

Parameter	In	Type	Description
id*	path	uuid	Job ID.

GET/api/jobs/:id/routing-decisionsGet routing audit trail

Returns all RoutingDecision records for the job — hard vetoes applied, AI candidate scores, selected device, and post-completion outcome labels used for model feedback.

Parameter	In	Type	Description
id*	path	uuid	Job ID.

Response

[{
  "id": "rd_01j9xn...",
  "stage": "print",
  "selectedBy": "ai",
  "selectedDeviceId": "dev_01j...",
  "hardVetoes": [{ "deviceId": "dev_02j...", "vetoCode": "substrate_gsm_exceeded" }],
  "candidates": [{ "deviceId": "dev_01j...", "scores": { "capabilityFit": 0.95, "queueFit": 0.88, ... } }],
  "outcome": { "status": "completed", "wastePercent": 1.2 }
}]

GET/api/jobs/dispatchFetch jobs for a connector

Used by connector agents to poll for jobs assigned to their connector. Returns jobs in queued state where the production stage connectorId matches.

Parameter	In	Type	Description
connectorId*	query	uuid	Connector agent ID.

PATCH/api/jobs/:id/statusUpdate job status

Used by connector agents to report stage progress and completion back to the cloud.

Parameter	In	Type	Description
id*	path	uuid	Job ID.
status*	body	string	New status value.
stage	body	string	Stage name if updating a specific production stage.

Devices

/api/devicesAuth required

Register and manage print devices. Each device has a capability envelope (substrate range, color spaces, finishing operations) and AI signals (queue depth, historical waste, SLA compliance) that the routing engine queries.

POST/api/devicesRegister a device

Request body

{
  "name": "HP Indigo 100K — Bay 3",
  "type": "digital_press",
  "adapter": "hp_indigo",
  "connectorId": "con_01j9xp...",
  "capabilities": {
    "substrates": ["coated", "uncoated"],
    "colorSpaces": ["CMYK", "RGB", "spot"],
    "finishing": ["perforate", "score"],
    "maxSubstrateGsm": 350,
    "minSubstrateGsm": 60,
    "maxSpeedSph": 4600
  }
}

Response

{ "id": "dev_01j9xq...", "status": "online", ... }

GET/api/devicesList all devices

Parameter	In	Type	Description
status	query	string	Filter by status: online \| offline \| error \| maintenance.

GET/api/devices/:idGet a device

Returns the device record including its full capability envelope and current AI signals.

Parameter	In	Type	Description
id*	path	uuid	Device ID.

PATCH/api/devices/:id/statusUpdate device status

Used by connector agents to push status changes and updated AI signals (queue depth, waste %, SLA rate, maintenance risk).

Parameter	In	Type	Description
id*	path	uuid	Device ID.
status*	body	string	online \| offline \| error \| maintenance.
aiSignals	body	object	Updated AI signal values from SNMP / device polling.

Connectors

/api/connectorsAuth required

On-premise connector agents self-register on first start and send heartbeats every 30 s. The cloud uses heartbeat data to surface agent health in the dashboard and to flag stale connectors.

POST/api/connectorsRegister a connector agent

Request body

{
  "name": "Plant Floor A — Building 2",
  "adapterType": "generic_rest",
  "version": "1.0.0"
}

Response

{ "id": "con_01j9xp...", "status": "online" }

GET/api/connectorsList all connectors

GET/api/connectors/:idGet a connector

Parameter	In	Type	Description
id*	path	uuid	Connector ID.

POST/api/connectors/:id/heartbeatSend a heartbeat

Sent every 30 s by the connector agent. Updates last-seen timestamp and resource metrics.

Parameter	In	Type	Description
id*	path	uuid	Connector ID.
cpuPercent	body	number	Agent host CPU usage 0–100.
memoryPercent	body	number	Agent host memory usage 0–100.
activeJobs	body	number	Jobs currently being processed.
queueDepth	body	number	Jobs waiting in the local queue.

Events (SSE)

/api/eventsAuth required

Real-time event stream using Server-Sent Events. Each connection is scoped to the requesting tenant — no cross-tenant data is visible. Reconnect with Last-Event-ID for resumable streams.

GET/api/eventsOpen SSE stream

Returns a persistent text/event-stream connection. Events are emitted as the tenant's jobs, devices, and AI signals change state. Event types: job.submitted · job.routed · job.queued · job.in_progress · job.completed · job.failed · device.online · device.offline · device.error · ai.intent.extracted · ai.routing.decided · alert.sla_breach

Parameter	In	Type	Description
Authorization*	header	Bearer <token>	JWT token.
Last-Event-ID	header	string	Resume stream from a prior event ID.

Response

data: {
  "tenantId": "ten_01j9x...",
  "eventType": "job.routed",
  "source": "routing-engine",
  "payload": { "jobId": "job_01j9xm...", "deviceId": "dev_01j9xq..." },
  "timestamp": "2026-06-22T14:32:01Z"
}

GET/api/events/recentGet recent events

Returns the last N events for the tenant (non-streaming). Useful for dashboard hydration on page load.

Parameter	In	Type	Description
limit	query	number	Max events to return (default 50).

Explore the full OpenAPI spec

Import into Postman, generate a client SDK, or browse interactively in Swagger UI.

System Architecture →Connector Guide →