API Reference

The live OpenAPI specification is always available at https://api.merion.com.au/openapi.yaml and the interactive documentation page at https://api.merion.com.au/docs. This reference documents only the publicly accessible surface — unauthenticated endpoints and the Forms API intake. Authenticated endpoints are described in the OpenAPI spec.

---

GET /health

Method

GET

URL

https://api.merion.com.au/health

Authentication

None required

Description

Returns the current operational status of the API hub. Suitable for uptime monitoring and health checks.

Example request

curl -s https://api.merion.com.au/health

Example response

{
  "status": "ok",
  "timestamp": "2026-06-29T00:00:00.000Z"
}

A 200 OK with status: "ok" indicates the hub is operational. A non-200 response or a status value other than "ok" should be treated as degraded. For historical uptime, see status.merion.com.au.

---

GET /docs

Method

GET

URL

https://api.merion.com.au/docs

Authentication

None required

Description

Human-readable API documentation page. Rendered from the OpenAPI specification.

Example request

curl -s https://api.merion.com.au/docs

Open in a browser for the full interactive experience.

---

GET /openapi.yaml

Method

GET

URL

https://api.merion.com.au/openapi.yaml

Authentication

None required

Description

Machine-readable OpenAPI 3.x specification in YAML format. The authoritative source of truth for all API routes, parameters, and schemas including authenticated endpoints.

Example request

curl -s https://api.merion.com.au/openapi.yaml -o merion-openapi.yaml

Import this file into Postman, Insomnia, or any OpenAPI-compatible tool to explore the full authenticated API surface.

---

GET /.well-known/openid-configuration

Method

GET

URL

https://api.merion.com.au/.well-known/openid-configuration

Authentication

None required

Description

OIDC discovery document served by auth.merion.com.au. Contains the issuer, authorisation endpoint, token endpoint, JWKS URI, and supported grant types. Clients should use this document to configure their OIDC library rather than hardcoding endpoint URLs.

Example request

curl -s https://api.merion.com.au/.well-known/openid-configuration | python3 -m json.tool

Key fields in the response

issuer

The canonical issuer URI — must be validated on every token you receive.

authorization_endpoint

Where to send the user for the authorisation code flow.

token_endpoint

Where to exchange the authorisation code for tokens.

jwks_uri

The JWKS endpoint for verifying JWT signatures (ES256).

code_challenge_methods_supported

Will include S256. Plain is not supported.

---

POST /public/forms/{key}

Method

POST

URL

https://api.merion.com.au/public/forms/{key}

Authentication

None required — this is the only write endpoint open without a token

Description

Accepts marketing and partner form submissions. Full documentation in the Forms API section.

Example request

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"form":"contact","fields":{"name":"Jane Smith","email":"[email protected]","message":"I have an enquiry."},"hp":""}' \
  https://api.merion.com.au/public/forms/contact

See the Forms API page for payload schemas, available keys, the honeypot field, and full success/error envelope shapes.

---

Error responses

All error responses follow a consistent envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": { "field": "Specific field error" }
  }
}

Common HTTP status codes:

200 OK

Request succeeded.

400 Bad Request

Malformed request body or missing required fields.

401 Unauthorized

Missing or invalid bearer token.

403 Forbidden

Valid token but insufficient scope.

404 Not Found

Route or resource does not exist.

422 Unprocessable Entity

Validation failed — see details.

429 Too Many Requests

Rate limit exceeded. Check Retry-After.

500 Internal Server Error

Unexpected server error. Report to Merion support.