​
Swappr API

Swappr is a UK council and housing-association tenant-swap platform. This documentation covers the public REST + WebSocket APIs that the mobile clients consume.

​
What’s in this site

  • Get Started — quickstart, authentication, and a tour of how the API works.
  • Conventions — how we paginate, return errors, rate-limit, support idempotency, and version. Read this before reading any endpoint reference.
  • API Reference — every endpoint, grouped by module. Each page follows the same template.
  • Realtime — Socket.IO events for the chat module.

​
Versioning

All endpoints live under /api/v1. We never break a v1 endpoint; breaking changes ship as /api/v2. See Versioning.

​
How requests work

  • Base URL (production): https://api.swappr.co.uk/api/v1
  • Base URL (dev): http://localhost:3000/api/v1
  • Authentication: Authorization: Bearer <accessToken> (RS256 JWT, 15-min TTL). See Authentication.
  • All payloads are JSON. Responses are JSON. Errors follow RFC 9457 Problem Details.
  • All times are ISO 8601 UTC. All money is { amountMinor: int, currency: 'GBP' }.

​
Generated artifacts

  • OpenAPI 3.1 spec: /openapi.json (generated from Zod schemas).
  • Postman collection: /postman/swappr.postman_collection.json (generated from the OpenAPI spec, with hand-tweaked example payloads).