API Reference

API Endpoints

1. GET /api-v3/cell-counter-mappings/<test_id>

• Description: Returns resolved cell counter mappings for a given test. If lab_id mappings exist they are preferred; otherwise default mappings (lab_id = NULL) are returned.
• Query params:
  • lab_id (optional) — lab scope to resolve lab-specific mappings
• Response (200):

{
	"mappings": [
		{ "key": "a", "cell_id": 1, "report_format_index": 1, "report_format_order": 1 },
		{ "key": "b", "cell_id": 2, "report_format_index": 2, "report_format_order": 2 },
		{ "key": "q", "cell_id": 5, "report_format_index": 3, "report_format_order": 3 }
	]
}

2. POST /api-v3/cell-counter-mappings/<test_id>

• Description: Bulk create or upsert mappings for the given test (optionally scoped to a lab). Uses upsert semantics (insert or update on conflict).
• Request body example:

{              
	"mappings": [
		{ "key": "a", "cell_id": 1, "report_format_index": 1, "report_format_order": 1 },
		{ "key": "b", "cell_id": 2, "report_format_index": 2, "report_format_order": 2 },
		{ "key": "q", "cell_id": 5, "report_format_index": 3, "report_format_order": 3 }
	]
}

• Notes:
  • Servers should validate uniqueness constraints (no duplicate keys per test+lab scope and one mapping per parameter).
  • For large imports, consider using a staging job or replace_all semantics (atomic DELETE + INSERT inside a transaction).

3. PATCH /api-v3/cell-counter-mappings/<test_id>

• Description: Update existing mappings (bulk partial update or upsert). Behavior mirrors POST but may support partial fields for patching.
• Request body example (single mapping update):

{
	"mappings": [
		{ "key": "1", "cell_id": 5, "report_format_id": 3607 }
	]
}

• Notes:
  • report_format_id may be accepted when updating by parameter id; the primary schema uses report_format_index + report_format_order for parameter position. Make sure the service maps either shape appropriately.
  • Responses:
    • 200: success with operation summary (inserted/updated counts)
    • 400: validation errors (bad payload)
    • 409: conflict (unique constraint violation)
    • 500: server error

4. GET /api-v3/cell-counter-mappings/cells/

• Description: Returns the list of available cell definitions used by the Cell Counter UI. This endpoint is used by the frontend to render available cells, colors, and default key suggestions.

• Query params: none

• Authentication: The service expects a valid session with a lab id; the current implementation verifies get_lab_id_from_session(request.session) and will return a validation error if the lab is not present in session.

• Response (200) example:

{
	"cells": [
		{
			"id": 1,
			"name": "Neutrophil",
			"bg_color_hex": "#FFFFFF",
			"fg_color_hex": "#000000",
			"default_key": "1",
			"is_disable": false,
			"created_at": 1678901234,
			"updated_at": 1678901234
		},
		{
			"id": 2,
			"name": "Lymphocyte",
			"bg_color_hex": "#F0F0F0",
			"fg_color_hex": "#111111",
			"default_key": "2",
			"is_disable": false,
			"created_at": 1678901234,
			"updated_at": 1678901234
		}
	]
}

Usage: the frontend calls this endpoint once on load (or caches results) and uses cells to populate the UI. When mapping rows are returned by the mappings endpoint, cell_id references an entry from this cells list.

Auth & Permissions

• These endpoints should reuse the platform's auth middleware. Only users with configuration/edit permissions for the target lab or global admin roles should be allowed to create/update mappings.

Errors

• Validation errors return 400 with a structured errors array describing problems.
• Unique constraint failures return 409 with a message describing the conflicting key or parameter.