Dokumentace REST API.

Overview

Medical translation API

Galenio API přijímá zdravotnický text, překládá ho do cílového jazyka a vrací buď jednoduchý překlad, nebo detailní report z validační pipeline. Služba je určena pro aplikace, portály a interní systémy, které potřebují překlad pacientské komunikace.

Core capabilities

• Překlad jednoho textu nebo dávky textů.
• Dva režimy odpovědi: translation a report.
• Deterministické kontroly pro dávkování, jednotky, čísla, negace a strukturu textu.
• Stavy položek ok, warning a blocked.
• Request trace přes request_id bez ukládání raw textu.

Quickstart

První request

Pro překlad stačí poslat zdrojový jazyk, cílový jazyk, text a klientský API klíč v hlavičce X-API-Key.

curl -X POST "https://product-api-gateway-2hiukp37.ew.gateway.dev/v1/translate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GALENIO_API_KEY" \
  -d '{
    "source_language": "en",
    "target_language": "cs",
    "text": "Take one 10 mg tablet every morning after breakfast."
  }'

Response

{
  "request_id": "req_01JQ8M7K2X4N9P6R3T5V",
  "response_mode": "translation",
  "results": [
    {
      "client_item_id": null,
      "status": "ok",
      "text": "Užívejte jednu 10mg tabletu každé ráno po snídani."
    }
  ]
}

Authentication

API keys

Klientské endpointy používají hlavičku X-API-Key. Admin endpointy používají hlavičku X-Admin-Key. Klíče jsou tenant-specific a mohou mít omezené scopes.

Scopes

Endpoints

Endpoint reference

Translate

POST /v1/translate

Endpoint podporuje single-text request přes text i batch request přes items. V jednom requestu musí být použita právě jedna z těchto variant.

Headers

Content-Type: application/json
X-API-Key: $GALENIO_API_KEY

Single text

{
  "source_language": "en",
  "target_language": "cs",
  "response_mode": "translation",
  "text": "Take one 10 mg tablet every morning after breakfast."
}

Batch with report

{
  "source_language": "en",
  "target_language": "cs",
  "response_mode": "report",
  "context": "Patient-facing medical instructions. Preserve dosage, units, frequency, negation, storage conditions, and warning meaning exactly.",
  "items": [
    {
      "client_item_id": "dose-1",
      "text": "Take one 10 mg tablet every morning after breakfast."
    },
    {
      "client_item_id": "warning-1",
      "text": "Do not take this medicine if you are allergic to penicillin."
    }
  ]
}

Schemas

Request and response schema

Request body

Batch item

Response body

{
  "request_id": "req_01JQ8M7K2X4N9P6R3T5V",
  "response_mode": "report",
  "results": [
    {
      "client_item_id": "dose-1",
      "status": "ok",
      "text": "Užívejte jednu 10mg tabletu každé ráno po snídani.",
      "code": null,
      "message": null
    }
  ],
  "report": {
    "items": [],
    "runtime": {}
  }
}

Statuses

Item status semantics

Blocked response example

{
  "request_id": "req_01JQ8M7K2X4N9P6R3T5V",
  "response_mode": "report",
  "results": [
    {
      "client_item_id": "dose-risk",
      "status": "blocked",
      "code": "critical_guardrail_failure",
      "message": "Translation blocked because final guardrails reported CRITICAL severity."
    }
  ],
  "report": {
    "items": [
      {
        "client_item_id": "dose-risk",
        "status": "blocked",
        "source_language": "en",
        "target_language": "cs",
        "final_translation": null,
        "guardrails": {
          "final": {
            "severity": "CRITICAL",
            "issues": []
          }
        }
      }
    ],
    "runtime": {}
  }
}

Limits

Languages and request limits

Supported languages

ar, bg, cs, de, en, ro, ru, es, uk, vi

Default limits

Tenant configuration may further restrict allowed languages, language pairs, batch size, character limits and usage quotas. Self-translation is rejected, for example en -> en.

Errors

Error response format

{
  "request_id": "req_01JQ8M7K2X4N9P6R3T5V",
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "status_code": 400,
    "details": {}
  }
}

Traces

Request trace lookup

Every translate response includes request_id. Use it for support and trace lookup. Trace records are metadata-only: they include counts, statuses, timings, guardrail summaries and usage metadata, but not raw source text, translated text or provider payloads.

GET /v1/admin/requests/{request_id}

Admins can read traces across clients with X-Admin-Key. Clients can read only their own traces when their key includes trace:read.

Admin API

Client and usage management

Admin endpoints are intended for operational tooling and require admin scopes. Do not expose admin keys in client-side applications.

Key rotation response

{
  "client": {
    "id": "8f4b7b2e-63dc-4cb6-99d8-5d236ec8bf42",
    "name": "patient-portal-production",
    "is_active": true,
    "scopes": ["translate:run"]
  },
  "api_key": "gln_live_[redacted]"
}

Safety

Guardrails and privacy

Galenio API validates translated output before returning it. Critical unresolved guardrail findings block the item and no translation text is returned.

Support

Access and support

Pro klientský API klíč, přístup k admin operacím nebo integrační dotazy napište na tomaskroupa@galenio.app.