Project Search (API v2)

DATAMIMIC exposes typed project search endpoints intended for paginated project listings.

Endpoints

• POST /api/v2/projects/search — Search projects visible to the current user (user auth).
• POST /api/v2/admin/projects/search — Search projects (admin) (admin auth).

Both endpoints use a backend-owned table-search envelope in the request body:

{
  "filters": { },
  "pagination": { "page": 1, "per_page": 10 },
  "sorting": { "sort_by": "id", "sort_order": "desc" }
}

Example: search by partial IDs (UUID fragments):

{
  "filters": { "q": "76b5aa94-" },
  "pagination": { "page": 1, "per_page": 10 },
  "sorting": { "sort_by": "id", "sort_order": "desc" }
}

Legacy note:

• These POST .../search endpoints do not use page / per_page query parameters; clients must send pagination in the request body.

Pagination rules:

• page is 1-based; page<=0 is clamped to 1
• per_page<=0 uses the API default (10)
• per_page is capped by server_settings.DB_ITEM_LIMIT (page-size cap only, no separate total-results cap)
• page is clamped to total_pages

Substring filters:

• All substring filters are case-insensitive (ILIKE %value%).

Request Model

ProjectSearchRequest

Body shape:

• filters — ProjectSearchFilters
• pagination — PaginationRequest
• sorting — ProjectSortConfig

ProjectSearchFilters:

Field	Type	Match semantics
q	string \| null	Free-text filter. Case-insensitive substring match across supported text fields and ID fields (project_id). Supports partial UUID fragments like 76b5aa94-.
project_id	string \| null	Exact match (== on Project.identifier)
project_name	string \| null	Substring match (ILIKE %value%, case-insensitive)
user_email	string \| null	Substring match across project members (ILIKE %value%, case-insensitive)
type	ProjectType \| null	Exact match (==)

Unknown fields are rejected with 422 (request models forbid extras).

Sorting

ProjectSortConfig:

• sort_by: one of id, tc_creation, tc_update
• sort_order: asc or desc (default: desc)

Default behaviour: sort by id descending (deterministic, tie-broken by id).

Response Model

Both endpoints return SearchProjectResponse:

• data: ProjectMetadataWithUsers[]
• meta:
• pagination: total_items, total_pages, current_page, per_page, next_page_num, prev_page_num
• sorting: the applied sorting config
• applied_filters: normalized filters actually applied by the server

ProjectMetadataWithUsers includes identifier, name, type, config, and users (when available).

Known Limitations (No Fake Features)

• No date-range filters (e.g. from/to, tc_creation_from, …)