Public read API

Overview

Three resource types are available without authentication:

Resource	List	Detail
Jobs	`GET /api/v1/jobs`	`GET /api/v1/jobs/{id}`
Events	`GET /api/v1/events`	`GET /api/v1/events/{id}`
Posts (articles)	`GET /api/v1/posts`	`GET /api/v1/posts/{id}`

These endpoints return published content only. Draft, archived, or moderated records are excluded.

Example request

No Authorization header is required:

GET /api/v1/jobs?limit=5&q=HGV+driver HTTP/1.1
Host: hgvtraders.com

{
  "data": {
    "jobs": [
      {
        "id": "cljob123abc",
        "slug": "hgv-class-1-driver-manchester",
        "title": "HGV Class 1 Driver",
        "department": "Transport",
        "contractType": "Full-time",
        "remote": false,
        "locationCity": "Manchester",
        "salaryFrom": 30000,
        "salaryTo": 45000,
        "salaryType": "ANNUAL",
        "companyName": "Acme Haulage",
        "organisationName": "Acme Trucks Ltd",
        "publishedAt": "2024-06-01T08:00:00.000Z",
        "createdAt": "2024-05-28T10:00:00.000Z"
      }
    ],
    "total": 128,
    "page": 1,
    "pages": 26
  }
}

See Pagination for page and limit parameters.

Field allow-list

Responses expose only intentionally public fields. Internal columns — moderation notes, draft metadata, organiser contact details, and similar — are never included.

Each resource type has a fixed allow-list maintained in the codebase. If a new database column is added, it is not automatically exposed; it must be explicitly opted in.

id, title, slug, department, contractType, salary fields, location fields, remote, companyName, closingDate, publishedAt, category, organisation.name — full list in the API Reference.

Events

id, slug, name, description, schedule and location fields, organiserName, admission/pricing fields, category — no private organiser contact details.

Posts

id, title, slug, summary, body, image URLs, publishedAt, category.

Sensitive columns (moderation state, internal notes, draft metadata) are never exposed on public read routes.

Search and filters

All list endpoints support free-text search via q (maximum 200 characters).

Jobs additionally support filters such as category, department, contractType, remote, city, manufacturer, experienceLevel, recruiterType, minSalary, and maxSalary.

Events and posts support q for search. Refer to the API Reference for the full query schema per endpoint.

There is no sort or order parameter on the public v1 contract.

Rate limits

Public read routes are limited to 60 requests per minute per client IP. See Rate limits.

Error responses

Status	Meaning
400	Invalid query parameters or search syntax
404	Resource not found or not published
429	Rate limit exceeded
503	Search backend temporarily unavailable

See Errors for details.

What is not available

There is no public read API for stock listings on the marketplace. Dealer stock is managed via the Stock API (bearer auth). For dealer-owned events (enquiries, stock changes, job applications), use Webhooks.