Mentor Location Repository - API Contract

GET /api/v1/location-records/api/v1/location-records

List all mentor location records for an organization

Public

Response Example

{
  "data": [
    {
      "record_id": "locr_a1b2c3",
      "mentor_id": "mentor_7f3a2b",
      "organization_id": "org_abc123",
      "lat": 59.9139,
      "lng": 10.7522,
      "geography_point": "POINT(10.7522 59.9139)",
      "recorded_at": "2026-03-26T08:00:00Z",
      "is_active": true
    },
    {
      "record_id": "locr_d4e5f6",
      "mentor_id": "mentor_4c91de",
      "organization_id": "org_abc123",
      "lat": 59.9272,
      "lng": 10.7112,
      "geography_point": "POINT(10.7112 59.9272)",
      "recorded_at": "2026-03-25T17:30:00Z",
      "is_active": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/location-records/api/v1/location-records/:mentor_id

Get the current location record for a specific mentor

Public

Response Example

{
  "record_id": "locr_a1b2c3",
  "mentor_id": "mentor_7f3a2b",
  "organization_id": "org_abc123",
  "lat": 59.9139,
  "lng": 10.7522,
  "geography_point": "POINT(10.7522 59.9139)",
  "recorded_at": "2026-03-26T08:00:00Z",
  "is_active": true
}

POST /api/v1/location-records/api/v1/location-records

Upsert a mentor's location record (insert or update if exists)

Public

Request Example

{
  "mentor_id": "mentor_7f3a2b",
  "organization_id": "org_abc123",
  "lat": 59.9139,
  "lng": 10.7522
}

Response Example

{
  "record_id": "locr_a1b2c3",
  "mentor_id": "mentor_7f3a2b",
  "organization_id": "org_abc123",
  "lat": 59.9139,
  "lng": 10.7522,
  "geography_point": "POINT(10.7522 59.9139)",
  "recorded_at": "2026-03-26T09:00:00Z",
  "is_active": true,
  "created_at": "2026-03-26T09:00:00Z",
  "upserted": true
}

PUT /api/v1/location-records/api/v1/location-records/:mentor_id

Explicitly update a mentor's stored location

Public

Request Example

{
  "lat": 59.93,
  "lng": 10.72,
  "organization_id": "org_abc123"
}

Response Example

{
  "record_id": "locr_a1b2c3",
  "mentor_id": "mentor_7f3a2b",
  "lat": 59.93,
  "lng": 10.72,
  "geography_point": "POINT(10.7200 59.9300)",
  "recorded_at": "2026-03-26T09:10:00Z",
  "updated_at": "2026-03-26T09:10:00Z"
}

DELETE /api/v1/location-records/api/v1/location-records/:mentor_id

Delete a mentor's location record (on consent revocation or account deletion)

Public

Response Example

{
  "mentor_id": "mentor_7f3a2b",
  "deleted": true,
  "deleted_at": "2026-03-26T09:15:00Z"
}

GET /api/v1/location-records/api/v1/location-records/bounds

Query location records within a spatial bounding box for a given organization

Public

Response Example

{
  "data": [
    {
      "record_id": "locr_a1b2c3",
      "mentor_id": "mentor_7f3a2b",
      "organization_id": "org_abc123",
      "lat": 59.9139,
      "lng": 10.7522,
      "geography_point": "POINT(10.7522 59.9139)",
      "recorded_at": "2026-03-26T08:00:00Z",
      "is_active": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "bounds_used": {
    "sw_lat": 59.89,
    "sw_lng": 10.7,
    "ne_lat": 59.95,
    "ne_lng": 10.8
  }
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}