GestaltMatcher API Documentation

API for GestaltMatcher Service

A REST API for GestaltMatcher image analysis. Accepts face images encoded as Base64 and returns genetic disorder predictions or face encodings.

The GestaltMatcher API (GM API) is a REST API to provide access to the GestaltMatcher service. GestaltMatcher Service is a next-generation phenotyping approach that can predict the disorder/gene by analyzing the frontal image (T.-C. Hsieh et al., 2022; Hustinx et al., 2023). Users can send the image via GM API and obtain the gestalt scores of disorders/genes predicted by GestaltMatcher. It can also be further integrated into users' variant prioritization platform to facilitate the exome variants prioritization, such as PEDIA approach (T. C. Hsieh et al., 2019). To access GM API, please contact Prof. Peter Krawitz via email (pkrawitz@uni-bonn.de).

For technical assistance please contact Dr. Tzung-Chien Hsieh (thsieh@uni-bonn.de) or Dr. Tom Kamphans (tom@kamphans.de).

Authentication

All endpoints except POST /api/auth require a Bearer token in the Authorization header.

Tokens expire after 10 minutes.

Authorization: Token token=<access_token>

Endpoints

POST /api/auth

Authenticate and obtain an access token.

Request

Parameter	Type	Description
`user`	string	User name
`password`	string	User password
`key`	string	Synonym to password

curl -X POST https://example.com/api/auth \
  -H "Content-Type: application/json" \
  -d '{"user": "GestaltMatcher", "password": "secret"}'

Response 200 OK

{ "token": "abc123..." }

Response 401 Unauthorized — wrong credentials.

POST /api/images

Submit an image for asynchronous analysis. The request is placed in a queue.

Request

Parameter	Type	Required	Description
`image[base64]`	string	yes	Base64-encoded PNG or JPEG image
`image[type]`	string	no	`"encode"` to request face encoding
`version`	string	no	`"beta"` to use the beta model

curl -X POST https://example.com/api/images \
  -H "Authorization: Token token=abc123..." \
  -H "Content-Type: application/json" \
  -d '{"image": {"base64": "<base64-string>"}}'

Response 200 OK

{ "msg": "Image is uploaded successfully.", "service_id": 42 }

Use service_id to poll for results.

Response 422 Unprocessable Entity — missing or invalid Base64 image.

GET /api/results/:service_id

Poll for the result of a previously submitted image.

curl https://example.com/api/results/42 \
  -H "Authorization: Token token=abc123..."

Response 200 OK — analysis complete. Body depends on consumer settings:

Encode jobs — returns facial encoding vectors:

{ "encodings": { "face_0": [...], "face_1": [...] } }

Boolean-results users — returns a restricted summary:

{
  "model_version": "1.0",
  "gallery_version": "2.0",
  "has_genetic_disorder": true,
  "has_genetic_disorder_dist_threshold": false,
  "service_id": 42
}

Full-results users — returns the complete analysis.

Response 202 Accepted — analysis still in progress; poll again.

Response 400 Bad Request — service_id not provided.

Response 401 Unauthorized — service belongs to a different consumer.

Response 404 Not Found — no service with that ID.

Response 500 Internal Server Error — analysis failed (face alignment, encoding, or evaluation error).

GET /api/get_results (deprecated)

Equivalent to GET /api/results/:service_id but accepts service_id as a query parameter.

curl "https://example.com/api/get_results?service_id=42" \
  -H "Authorization: Token token=abc123..."

Use GET /api/results/:service_id instead.

Status Codes Summary

Code	Meaning
200	OK — request succeeded
202	Accepted — analysis still running, poll again
400	Bad Request — missing required parameter
401	Unauthorized — invalid/expired token or wrong consumer
404	Not Found — service ID does not exist
422	Unprocessable Entity — invalid or missing image
500	Internal Server Error — analysis pipeline failed
503	Service Unavailable — database is unreachable

Typical Async Workflow

1. POST /api/auth          → obtain token
2. POST /api/images        → submit image, receive service_id
3. GET  /api/results/:id   → poll until 200 (or 500)

GestaltMatcher AI