Meet the API

VeloxFactory ships with a fully capable REST API, and it is not an afterthought. Every action you can perform in the frontend can also be performed via the API, because the frontend and the API share the same controller methods. There is no separate implementation, no feature gap, no second-class citizen.

This makes the API a genuine alternative to the UI, not just an integration bolt-on. Automate report rendering in your CI pipeline, trigger prints from your ERP, manage report configurations programmatically, have VeloxFactory run the whole thing on a schedule, all with the same logic that powers the frontend you already know.

Authentication

The API uses token-based authentication via Laravel Sanctum. Every request must include a Bearer token in the Authorization header.

Authorization: Bearer your-api-token

Tokens are issued and revoked per user in the user management section of the frontend. A request authenticated by a token cannot create or revoke tokens, so a leaked token cannot renew itself and revoking it actually locks it out. A revoked token is rejected immediately, there is no grace period.

{
  "success": false,
  "errors": ["This API token has been revoked."],
  "status": 401
}

The audit trail records which token was used for every create and update operation across all models, so every API action is fully traceable.

Authentication Errors

Base URL

All API v1 endpoints are prefixed with:

/api/v1/

Referencing Records

Wherever a request points at another record, it accepts either the numeric ID or the unique name of that record. These two are the same call:

POST /api/v1/report-config/12/render
POST /api/v1/report-config/Shift Report/render

The same holds inside request bodies, for report contexts, connection configs, mailers, mail templates and schedules alike, so a payload stays readable without a lookup table of IDs. A Report History Record is addressed by its ID or by its trace id, which is what makes a trace id worth carrying through your own systems.

Response Structure

All API responses follow a consistent envelope format.

Success, list endpoint:

{
  "success": true,
  "count": 25,
  "data": [ { ... }, { ... } ],
  "links": {
    "first": "https://your-instance/api/v1/report-print-task?status=pending&page=1",
    "last": "https://your-instance/api/v1/report-print-task?status=pending&page=3",
    "prev": null,
    "next": "https://your-instance/api/v1/report-print-task?status=pending&page=2"
  },
  "meta": {
    "pagination": {
      "currentPage": 1,
      "lastPage": 3,
      "perPage": 25,
      "total": 61,
      "from": 1,
      "to": 25,
      "hasMorePages": true,
      "path": "https://your-instance/api/v1/report-print-task"
    }
  },
  "status": 200
}

Success, single record:

{
  "success": true,
  "count": 1,
  "data": { ... },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-print-task/256"
    }
  },
  "status": 200
}

Error:

{
  "success": false,
  "errors": ["Descriptive error message"],
  "meta": {},
  "status": 404
}

Every success response that carries data has the same shape, whether it returns a list, a single record, a freshly created record or a render result. A client parses one envelope for every endpoint.

• count is the number of records in data: the records on the current page for a list, 1 for a single record.
• links point to the first, last, previous and next page. A link that does not exist is null. Responses that are not paginated have all four links null.
• meta.pagination describes the page, see Pagination. A response that is not paginated reports exactly one page.
• meta carries further contextual information next to pagination, such as the traceId of a render run or the mailing result.

Error responses have no links and no pagination block.

Pagination

All list endpoints (GET /user, GET /report-config, GET /report-print-task and every other GET on a resource without an id) return their records page by page. Two query parameters control the page:

The values of the pagination block:

Filters such as status, type or isActive apply before the records are split into pages, so total counts the filtered result. The links in links carry all query parameters of the request, a client follows links.next until it is null and keeps its filters on every page.

A page behind the last one returns 200 with an empty data array. A page below 1, a perPage above 100 or a non-numeric value returns 422.

To read every record, request perPage=100 and follow links.next. Every page is a request of its own and counts against the rate limit.

The two placeholder catalogs (GET /mail-template/placeholders, GET /scheduled-job/placeholders) are not paginated and always return one page.

The page size default and maximum are set with API_PER_PAGE_DEFAULT and API_PER_PAGE_MAX, see Configuration and Data Models.

Query Parameters

Most GET endpoints and the render endpoint share a common set of query parameters that control what is included in the response. They are additive, combine them freely.

Example, retrieve a single report config with all relations, media, and audit data:

GET /api/v1/report-config/1?withRelations=true&withMedia=true&withAudit=true

Audit Segment

When withAudit=true is set, every record in the response carries an audit block:

"audit": {
  "createdAt": "2026-05-08 11:26:30",
  "createdByUser": 2,
  "createdByToken": null,
  "creationMethod": "Frontend",
  "updatedAt": "2026-05-08 13:31:35",
  "updatedByUser": 1,
  "updatedByToken": "Postman",
  "updateMethod": "API"
}

creationMethod and updateMethod are derived automatically, "API" when a token was used, "Frontend" when the action came through the UI. A run of a scheduled job fills these exactly like a direct call does, with the owner of the schedule and the token it runs with.

Render-Specific Request Body

The render endpoint (POST /api/v1/report-config/{id}/render) accepts the following fields in the request body (JSON).

Laconic Responses

By default, a render response is fully populated, it includes the echoed input, the PDF output, the linked ReportConfig, the created ReportHistoryRecord, and the ReportPrintTask and ReportMailTask if applicable. In high-frequency or bandwidth-sensitive scenarios, add laconicResponse=true to strip everything down to just the PDF output.

The Same Body on a Schedule

This body is also what a render job of the Job Scheduler stores. A request you have tested here can be dropped into the payload of a schedule unchanged, minus traceId, which every run generates for itself. See Render Jobs.

Rate Limiting

The API enforces a configurable rate limit per token. The default is 10 requests per minute. When the limit is exceeded:

{
  "success": false,
  "message": "Too many requests! The current rate limiting is 10 requests per minute.",
  "status": 429
}

The limit is adjusted via the API_RATE_LIMIT_PER_MINUTE environment variable, see Configuration and Data Models.

Endpoints Overview

A Practical Example: The Full Render Response

A render call returns a ReportRendering object. By default it is fully populated, you see the input you sent, the PDF output, and the linked records that were created.

{
  "success": true,
  "count": 1,
  "data": {
    "model": "ReportRendering",
    "traceId": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61",
    "input": {
      "parameters": {
        "P_ARTICLE_NUMBER": "4561287-154"
      },
      "data": null
    },
    "output": {
      "reportPdfFileName": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61.pdf",
      "reportPdfBase64": "JVBERi0xLjQ...",
      "reportUrl": null
    },
    "reportConfig": { "..." },
    "reportHistoryRecord": { "..." },
    "reportPrintTask": null
  },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "traceId": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61",
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-config/12/render"
    }
  },
  "status": 200
}

Add laconicResponse=true and the response collapses to just output, no echoed input, no embedded related records. Ideal for automated pipelines that only need the PDF.