v0 App

Authentication: All /api/v1/* endpoints require gateway signature authentication via X-Gateway-Key, X-Gateway-Signature, X-Gateway-Timestamp, and X-Request-Id headers.

Workflows & Relationships


================================================================================
                                 DATA MODEL
================================================================================

TEMPLATE                          TEMPLATE_TRANSLATIONS
+------------------+              +------------------------+
| id               |----1:N------>| template_id            |
| category_id      |              | language_code (en, nl) |
| status           |              | title                  |
| visibility       |              | description            |
| organization_id  |              | ai_guidance            |
+------------------+              +------------------------+
         |
         | 1:N (via template_sections junction table)
         v
TEMPLATE_SECTION
+------------------+
| template_id      |
| section_id       |
| display_order    |
+------------------+
         |
         | N:1
         v
SECTION                           SECTION_TRANSLATIONS
+------------------+              +------------------------+
| id               |----1:N------>| section_id             |
| output_format    |              | language_code          |
| visibility       |              | name                   |
| status           |              | description            |
| specialty        |              | ai_guidance            |
| owner_id         |              +------------------------+
| owner_type       |
| source_section_id|------> Points to original if duplicated
+------------------+
         |
         | 1:N (only when output_format = structured_fields)
         v
SECTION_FIELD                     SECTION_FIELD_TRANSLATIONS
+------------------+              +------------------------+
| id               |----1:N------>| section_field_id       |
| field_type       |              | language_code          |
| unit_of_measure  |              | name                   |
| display_order    |              | description            |
| is_required      |              +------------------------+
| min_value        |
| max_value        |
+------------------+


================================================================================
                               KEY CONCEPTS
================================================================================

1. TRANSLATIONS
   - Each Template, Section, and Field has its own translation table
   - Keyed by language_code (e.g., 'en', 'nl')
   - Query with ?language=nl to get Dutch, otherwise returns first available

2. SECTION REFERENCES
   - Sections in templates are always references to the original section
   - Updates to a section are reflected in all templates using it
   - For independent copies, use POST /sections/:id/duplicate first

3. owner_id + owner_type (for sections)
   - Sections owned by your organization (owner_type=organization) are shared
   - Sections owned by users (owner_type=user) are personal
   - Filter by owner_id to find organization-maintained sections

4. missing_languages
   - Template shows: missing_languages_in_sections (any language missing in any section)
   - Each section shows: missing_languages (languages template has but section lacks)
   - Use this to identify and complete translation gaps

5. output_format (for sections)
   - free_text:         AI generates prose
   - bullet_points:     AI generates bullet list
   - structured_fields: AI fills predefined fields with validation

Common Workflows

Check supported languages

GET/api/v1/languages

Get the list of supported languages (e.g., 'en', 'nl').

Create template with translations

POST/api/v1/templates

Create a template with at least one translation. Add more languages as needed.

{
  "category_id": "uuid-of-category",
  "status": "draft",
  "translations": [
    {
      "language_code": "en",
      "title": "Cardiology Consultation",
      "description": "Standard template for cardiology consultations",
      "ai_guidance": "Summarize the patient's cardiovascular symptoms..."
    },
    {
      "language_code": "nl",
      "title": "Cardiologisch Consult",
      "description": "Standaard sjabloon voor cardiologische consulten",
      "ai_guidance": "Vat de cardiovasculaire symptomen van de patiënt samen..."
    }
  ]
}

Add translations later (optional)

PATCH/api/v1/templates/:id

Add or update translations for additional languages at any time.

{
  "translations": [
    {
      "language_code": "de",
      "title": "Kardiologische Beratung",
      "description": "...",
      "ai_guidance": "..."
    }
  ]
}