Catalogues API

List Catalogues

Get a paginated list of all catalogues.

Endpoint: GET /api/catalogues

Query Parameters:

Parameter	Type	Required	Default	Description
page	number	No	1	Page number
pageSize	number	No	10	Items per page
search	string	No		Search term for catalogue name

Response: 200 OK

{
  "catalogues": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "GeoNet - New Zealand",
      "created_at": "2024-10-24T12:00:00.000Z",
      "updated_at": "2024-10-24T12:00:00.000Z",
      "status": "active",
      "event_count": 1434,
      "min_latitude": -47.5,
      "max_latitude": -34.2,
      "min_longitude": 165.8,
      "max_longitude": 179.2,
      "min_magnitude": 2.0,
      "max_magnitude": 7.8,
      "start_time": "2024-01-01T00:00:00.000Z",
      "end_time": "2024-10-24T12:00:00.000Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 10
}

Create Catalogue

Create a new earthquake catalogue.

Endpoint: POST /api/catalogues

Request Body:

{
  "name": "My Earthquake Catalogue",
  "events": [
    {
      "id": "event-001",
      "time": "2024-10-24T12:34:56.789Z",
      "latitude": -41.2865,
      "longitude": 174.7762,
      "depth": 33.0,
      "magnitude": 5.2,
      "magnitude_type": "ML",
      "region": "Wellington Region"
    }
  ]
}

Response: 201 Created

The response spreads all catalogue fields plus a validation report:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Earthquake Catalogue",
  "event_count": 1,
  "created_at": "2024-10-24T12:00:00.000Z",
  "importMessage": "Successfully imported all 1 events.",
  "partialImport": false,
  "validationReport": {
    "totalSubmitted": 1,
    "successfullyImported": 1,
    "failedValidation": 0,
    "successRate": 100,
    "invalidEvents": []
  }
}

Error Responses: - 400 Bad Request: Invalid request body, missing required fields, or all events failed validation - 500 Internal Server Error: Database error

Get Catalogue

Get details of a specific catalogue.

Endpoint: GET /api/catalogues/{id}

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Catalogue UUID

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "GeoNet - New Zealand",
  "created_at": "2024-10-24T12:00:00.000Z",
  "updated_at": "2024-10-24T12:00:00.000Z",
  "status": "active",
  "event_count": 1434,
  "min_latitude": -47.5,
  "max_latitude": -34.2,
  "min_longitude": 165.8,
  "max_longitude": 179.2,
  "min_magnitude": 2.0,
  "max_magnitude": 7.8,
  "start_time": "2024-01-01T00:00:00.000Z",
  "end_time": "2024-10-24T12:00:00.000Z"
}

Error Responses: - 404 Not Found: Catalogue does not exist

Update Catalogue

Update catalogue metadata (currently only name).

Endpoint: PATCH /api/catalogues/{id}

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Catalogue UUID

Request Body:

{
  "name": "Updated Catalogue Name"
}

Response: 200 OK

{
  "success": true
}

Error Responses: - 400 Bad Request: Invalid catalogue name - 404 Not Found: Catalogue does not exist

Delete Catalogue

Delete a catalogue and all its events.

Endpoint: DELETE /api/catalogues/{id}

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Catalogue UUID

Response: 200 OK

{
  "success": true
}

Error Responses: - 404 Not Found: Catalogue does not exist - 500 Internal Server Error: Database error