API reference

Search

Answer a customer's training question with matching OMS courses, dates and related content.

POSThttps://oms-api.mainconsulting.co.uk/api/public/v1/search

Request headers

Authorization

required

Bearer <your API key>

Content-Type

required

application/json

Request body

query

string · required

The visitor's question in plain English, 1–500 characters. E.g. "First aid training in Leicester next month".

context

string · optional, nullable

The context value from the previous response, to continue a conversation. Send null or omit for a new search. See Conversation context.

Any other field is rejected with 400 invalid_request. Maximum body size is 8 KB.

curl https://oms-api.mainconsulting.co.uk/api/public/v1/search \
  -H "Authorization: Bearer $OMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "I need first aid training for my staff."}'

Response

Always JSON. A successful search returns 200 with the search response object. Errors use the error object.

status values

results

At least one course or online activity matched. Render them.

no_results

Nothing suitable was found. answer explains why; follow_up_question may suggest broadening (e.g. removing a date).

clarification_needed

The question was too vague (e.g. "I need training"). Show follow_up_question and send the reply with context.

out_of_scope

The message wasn't about finding training. Show answer.

Response headers

X-Request-Id

string

Same as request_id in the body. Quote it when contacting support.

X-RateLimit-Limit / Remaining / Reset

integer

Per-minute limit, remaining requests this minute, seconds until reset.

Retry-After

integer

Seconds to wait, on 429 and 503 responses.

Health check

GET https://oms-api.mainconsulting.co.uk/api/public/v1/health needs no key and returns {"status":"ok","catalogue_synced_at":…,"content_synced_at":…}.