API Reference

Version: v1 · Base URL: https://caravanguide.co.uk/api/v1/

Welcome to the Caravan Guide API documentation. This reference is public - browse endpoints, authentication, and error codes without an account. Calling the API still requires provisioned credentials; unauthenticated requests receive structured 401 errors. Use the Download PDF Guide button in the sidebar or header for a printable copy.

Quick Start

1. Obtain credentials (API key or OAuth client pair) from your account manager.
2. Use your credentials to authenticate requests (see Authentication).
3. Build partner search UIs with /valuations/catalog (cascade dropdowns and pre-fill).
4. Resolve trade or alias listing text with /valuations/resolve, then fetch prices via /valuations/search.
5. Explore all available Endpoints.
6. If something goes wrong, check the Error Codes reference.

Partner catalogue integration

Most partner sites need a make → model → year → size → bedroom selector before showing a valuation. Use the catalogue endpoints for dropdown data (no prices), then search or pricing for GBP figures.

1. Page load with known listing data - GET /valuations/catalog?bootstrap=1 with optional pre-fill query params. Response includes all applicable options lists and a selection object with per-field valid / canonical values.
2. User changes one field - GET /valuations/catalog?step=… with parent filters and any pre-fill params for fields already set.
3. Listing uses trade or alias names - GET /valuations/resolve to obtain canonical manufacturer, model_name, and model_year (and optional family_id).
4. User completes selection - GET /valuations/search using canonical values from selection.*.canonical or resolve.

See the full workflow, parameter reference, and examples on the Endpoints page.

Design Principles

• HTTPS only. All requests must use TLS 1.2 or higher. HTTP requests are not accepted.
• JSON throughout. All request bodies and responses use application/json. There is no XML or HTML output on API routes.
• URL-versioned. The current version is /api/v1/. Breaking changes always introduce a new version path. Old versions receive a deprecation notice before being retired.
• Consistent error envelopes. Every error response follows the same structure with a machine-readable error.code field.
• Request ID correlation. Every response includes X-Request-Id. Include this in any support request.
• Rate limit headers. X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are returned on every authenticated response.

Response Envelope

Success

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "a1b2c3d4e5f6",
    "version": "v1"
  }
}

Error

{
  "success": false,
  "error": {
    "code": "machine_readable_code",
    "message": "Human-readable description."
  },
  "meta": {
    "request_id": "a1b2c3d4e5f6",
    "version": "v1"
  }
}

Environments

Environment	Credential prefix	Description
Sandbox	cg_sandbox_	Static test data. Safe for integration testing - no live valuations, no live certificates.
Live	cg_live_	Real production data. Requests are metered against your monthly allowance.

Using a live credential against the sandbox or vice-versa returns 403 credential_environment_mismatch.

Support

If you encounter an unexpected error, send us the X-Request-Id header value from the failing response and we can trace the exact request in our logs.

Contact: