API Overview

Qinfinite Automation Hub exposes two primary REST API surfaces, each served by a dedicated microservice:

Service	Default Port	Purpose
Job Executor	9000	Job CRUD, step management, execution control, search, logging
Global Configurator	8081	Connection credentials, global variables, certificates, datasets, files, API templates

A third service, the MCP Server (port 8080), provides the AI-facing interface via Model Context Protocol. See AI Integration for MCP-specific documentation.

Base URLs

Job Executor:       http://localhost:9000
Global Configurator: http://localhost:8081
MCP Server:         http://localhost:8080

In production, these are typically behind a reverse proxy or API gateway with paths like /api/job-executor/, /api/configurator/, etc.

Authentication

All API endpoints are secured with role-based access control via Spring Security. Each endpoint requires a specific authority (permission) in the caller's authentication token.

Authorities follow the pattern:

{Service}:{Resource}:{Action}

Examples:

Authority	Description
JobExecutor:Job:upsert	Create or update jobs
JobExecutor:Job:read	Read job details
JobExecutor:Job:delete	Delete jobs
JobExecutor:JobExecution:read	Read execution data
GlobalConfigurator:Connection:upsert	Create or update connections
GlobalConfigurator:Connection:read	Read connection details
GlobalConfigurator:GlobalVariable:upsert	Create or update global variables

Pass the authentication token in the Authorization header:

curl -H "Authorization: Bearer <token>" http://localhost:9000/jobs/{id}

Common Response Format

All API responses use a consistent ApiResponse wrapper:

{
  "status": "Success",
  "message": "Human-readable description of the result",
  "data": { },
  "error": null,
  "meta": null
}

Fields

Field	Type	Description
status	string	"Success" or "Error".
message	string	Description of what happened.
data	any	The response payload. Type varies by endpoint.
error	object | null	Error details when status is "Error". Contains code and message.
meta	object | null	Pagination metadata for list endpoints.

Pagination Metadata

Paginated endpoints include a meta object:

{
  "meta": {
    "totalElements": 142,
    "page": 0,
    "size": 10
  }
}

Error Handling

When an error occurs, the response includes an error object:

{
  "status": "Error",
  "message": "Failed to fetch job",
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Job with ID 'job-invalid' not found"
  },
  "meta": null
}

HTTP Status Codes

Code	Meaning
200	Success
201	Resource created
204	Success with no response body (e.g., delete)
400	Bad request (validation error, invalid input)
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Resource not found
500	Internal server error

Content Type

All endpoints accept and return application/json:

curl -X POST http://localhost:9000/jobs/upsert \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{ "name": "My Job" }'

API Sections

Job Executor APIs

• Jobs API -- CRUD operations for job definitions.
• Execution API -- Start, stop, pause, resume, and monitor executions.
• Steps API -- Manage steps within jobs.
• Search API -- Advanced search and filtering.

Global Configurator APIs

• Global Configurator Overview -- Service overview and resource types.
• Connections API -- Manage connection credentials.
• Variables API -- Manage global variables.