API Reference

The TrustRelay REST API is served by the trustrelay-api Go service.

Base URL

Always relative to the customer’s deployment (e.g. https://my-instance.trustrelay.io). All paths below are relative to this base.

Authentication

Requests to protected routes without a valid session/token return 401 Unauthorized.

Response envelope

All JSON endpoints (except binary media and MCP stream endpoints) wrap their response:

{ "value": <T>, "error": { "code": "...", "message": "..." } }

On success, error is omitted. On failure, value is omitted and error is populated.

Exceptions (raw responses, not wrapped):

• GET /api/logo
• GET /api/products/{productversionid}/cover
• POST /api/export/dxf
• /mcp and /api/mcp (MCP stream)

Rate limiting

Rate limiting is enforced per IP address on GET, POST, DELETE, PUT, and PATCH methods. The rate is controlled by the THROTTLE_REQUESTS_PER_SECOND environment variable. Exceeding the limit returns 429 Too Many Requests.

Timeouts

Auth

POST /api/auth/login

Authenticates a user and sets a session cookie.

Request:

{ "email": "user@example.com", "password": "..." }

Response 200:

{ "value": { "token": "...", "expires_at": 1234567890 } }

POST /api/auth/logout

Invalidates the current session. The session cookie is cleared.

POST /api/auth/verify

Validates the current session cookie. Used by the SvelteKit hooks.server.ts on every page load.

Response 200:

{
  "value": {
    "user": {
      "account_id": "uuid",
      "email": "user@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "organisation_id": "uuid",
      "is_org_anchor": false,
      "is_user_owner": true,
      "is_user_deputy": false,
      "lang": "en",
      "is_org_external": false
    },
    "settings": {
      "tenant_name": "My Platform",
      "logo_url": "https://..."
    },
    "unread_notifications": 2,
    "unread_inbox_messages": 0
  }
}

Version

GET /api/version

Returns build information. No authentication required.

Response 200:

{
  "value": {
    "app_name": "trustrelay-api",
    "version": "1.2.3",
    "build_time": "2026-04-07T00:00:00Z",
    "git_hash": "abc1234"
  }
}

Settings

All settings endpoints require a valid session.

Password reset

Users

Current user (self)

Organisations

Data products

{productversionid} is the data_product_version_id UUID. {productid} is the parent data_product_id.

Listing and creating

Product lifecycle

Metadata sections

Each section has a matching GET and PUT endpoint under /api/products/{productversionid}/:

Cover image

Messaging and queries

Agreements

Geo & time views

Search

GET /api/search?query=<term>&scope=<scope>

Full-text search over product general_info JSONB. Returns []ProductBasicInfo.

Access requests

See Access Management for business rules and status lifecycle.

Invitations

Images

GET /api/images/previews?search=<term>

Proxies to the configured image service (e.g. Unsplash) to return cover image candidates. Requires the image integration to be enabled in Settings → Apps.

JSON-RPC

POST /api/jsonrpc

Executes named product queries via DuckDB. Uses JSON-RPC 2.0 request format. 60-second timeout.

MCP

Authentication: Authorization: Bearer <PAT>. No timeout. See MCP Integration.

DXF export

POST /api/export/dxf
Content-Type: application/json

Accepts a GeoJSON FeatureCollection. Returns a binary application/dxf attachment.

Error codes