Backend API Reference

1. Introduction

Welcome to the SynergyHub Backend API. This document provides a comprehensive overview of the RESTful endpoints and WebSocket events available for interacting with the platform. The API is designed around domain-specific resources like Users, Source of Truth (SoT), Use Cases, and Prompts.

Base URL: All REST API endpoints are relative to the service's base URL. For production, this is:

 Copyhttps://ai-assistant-api-760853151287.us-central1.run.app

Conventions

• All request and response bodies are in JSON format.
• Successful requests will return a 2xx status code.
• Client errors will return a 4xx status code.
• Server errors will return a 5xx status code.
• Object identifiers (e.g., user_id, sot_id) are MongoDB ObjectIds represented as strings.

2. Authentication

The API uses Firebase ID Tokens (JWT) for authentication. All protected endpoints require a valid token to be passed in the Authorization header.

Header Format:

 CopyAuthorization: Bearer <YOUR_FIREBASE_ID_TOKEN>

User Context

Upon successful token verification, the backend creates a trusted AuthenticatedUserContext for the duration of the request. This context includes:

• user_id: The user's unique MongoDB _id.
• firebase_uid: The user's Firebase UID.
• tenant_id: The user's primary tenant.
• is_superadmin: A boolean flag indicating if the user has superadmin privileges.

Roles

• User: A standard authenticated user. Can access their own data and data shared with them based on their memberships (accounts, groups).
• Superadmin: A user with the system_role of SUPERADMIN. Has universal access to all data across the system. Endpoints requiring this role are explicitly marked.

3. Common Error Responses

Errors are returned with a standard JSON structure.

Example 400 Bad Request / Validation Error:

 Copy{
  "status": "error",
  "message": "Invalid input data.",
  "details": [
    {
      "loc": ["name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Example 401 Unauthorized:

 Copy{
  "code": "AUTH_INVALID_TOKEN",
  "description": "Token is invalid or revoked: The Firebase ID token has been revoked."
}

Example 403 Forbidden:

 Copy{
  "code": "FORBIDDEN",
  "description": "This action requires superadmin privileges."
}

Example 404 Not Found:

 Copy{
  "status": "error",
  "message": "Solution not found."
}

4. WebSocket API

The WebSocket API provides real-time, bidirectional communication for features like live transcription and interactive coaching.

Namespace: /general

4.1. Connection & Authentication Flow

1. Client Connects: The client establishes a WebSocket connection to the /general namespace.
2. Server Requests Authentication: The server emits a request_authentication event.
3. Client Authenticates: The client emits an authenticate event with its Firebase ID token.
4. Server Confirms: The server responds with auth_success or auth_failed. Once successful, the session is considered authenticated.

4.2. Events Emitted by Client

4.3. Events Emitted by Server

5. REST API Endpoints

5.1. Authentication & User Context

Get User Profile & Context

Endpoint: GET /api/auth/verify

Description: Verifies the user's Firebase token and returns their complete profile and accessible hierarchy (solutions, accounts, groups). This is the primary endpoint to call after a user logs in.

Authentication: User Token Required

Response 200 OK:

 Copy{
  "profile": {
    "_id": "6650a3123b4c5d6e7f8a9b0c",
    "firebaseUid": "FIREBASE_UID_HERE",
    "email": "user@example.com",
    "system_role": "user",
    "memberships": [
      {
        "account_id": "6650a3123b4c5d6e7f8a9b0a",
        "solution_id": "6650a3123b4c5d6e7f8a9b0b",
        "unit_id": "6650a3123b4c5d6e7f8a9b0a",
        "unit_type": "account",
        "roles": ["account_admin"]
      }
    ]
  },
  "solutions": [ { "id": "...", "name": "...", "branding": {...} } ],
  "accounts": [ { "id": "...", "name": "...", "user_roles_in_account": ["..."] } ],
  "groups": [ { "id": "...", "name": "...", "account_id": "...", "user_roles_in_group": ["..."] } ],
  "status": "success",
  "message": "Token verified and user profile retrieved."
}

5.2. Conversation Use Cases

Manage the configurations for different types of conversations (e.g., interviews, symptom checkers).

Create a Conversation Use Case

Endpoint: POST /api/conversation-use-cases

Description: Creates a new use case configuration.

Authentication: User Token Required

Request Body:

 Copy{
    "name": "Senior Developer Interview",
    "description": "A use case for conducting technical interviews.",
    "use_case_type": "INTERVIEW",
    "v2v_prompt_id": "6650a3123b4c5d6e7f8a9b1a",
    "contextual_analyzer_prompt_id": "6650a3123b4c5d6e7f8a9b1b",
    "sot_ids": ["6650a3123b4c5d6e7f8a9b1c"],
    "ui_template_name": "KEYWORD_BOXES",
    "keywordGroups": [
        {
            "groupName": "Python Experience",
            "keywords": ["Flask", "Django", "AsyncIO"]
        }
    ]
}

Response 201 Created: The full Conversation Use Case object.

List Conversation Use Cases

Endpoint: GET /api/conversation-use-cases

Description: Lists all use cases accessible to the authenticated user.

Authentication: User Token Required

Response 200 OK: An array of Conversation Use Case objects.

(Other standard CRUD endpoints GET /<id>, PUT /<id>, DELETE /<id> are also available.)

5.3. Source of Truth (SoT)

Manage the knowledge base documents that provide context to the AI.

Create a SoT Document

Endpoint: POST /api/sots

Description: Creates a new SoT document. The content field can be any valid JSON object.

Authentication: User Token Required

Request Body:

 Copy{
  "title": "Company Onboarding Policy",
  "category": "HR",
  "access_scope": "ACCOUNT",
  "account_id": "6650a3123b4c5d6e7f8a9b0a",
  "content": {
    "policy_version": "1.3",
    "sections": [
      { "title": "First Day", "details": "..." }
    ]
  }
}

Response 201 Created: The full SoT Document object.

List SoT Documents

Endpoint: GET /api/sots

Description: Lists all SoT documents accessible to the user. Supports filtering via query parameters (e.g., ?category=HR).

Authentication: User Token Required

Response 200 OK: An array of SoT Document objects.

(Other standard CRUD endpoints GET /<id>, PUT /<id>, DELETE /<id> are also available.)

5.4. Prompts

Manage the prompt templates that guide the AI's behavior.

Create a Prompt

Endpoint: POST /api/prompts

Description: Creates a new prompt definition.

Authentication: User Token Required

Request Body:

 Copy{
  "prompt_id": "summarize-meeting-v1",
  "name": "Summarize Meeting Transcript",
  "description": "Creates a concise summary with action items from a transcript.",
  "category_id": "SOT_UPDATE_SUGGESTIONS",
  "content": "Please summarize the following transcript and list the action items: {{new_transcript_content}}",
  "associated_llm_model_id": "gpt-4.1-mini-2025-04-14",
  "input_parameters": [
    { "name": "new_transcript_content", "required": true }
  ],
  "access_scope": "USER"
}

Response 201 Created: The full Prompt Definition object.

List Prompts

Endpoint: GET /api/prompts

Description: Lists the latest version of all prompts accessible to the user. Supports filtering (e.g., ?category_id=..., ?status=ACTIVE).

Authentication: User Token Required

Response 200 OK: An array of Prompt Definition objects.

(Other standard CRUD endpoints GET /<id>, PUT /<id>, DELETE /<id> are also available.)

5.5. LLM Models

Manage the definitions of available Large Language Models.

List LLM Models

Endpoint: GET /api/llm-models

Description: Lists all available LLM model definitions. Can be filtered by capability (e.g., ?capability=chat).

Authentication: User Token Required

Response 200 OK:

 Copy[
  {
    "_id": "6650a3123b4c5d6e7f8a9b2a",
    "model_id": "gpt-4.1-mini-2025-04-14",
    "name": "GPT-4o Mini",
    "provider": "openai",
    "capabilities": ["chat", "reasoning"],
    "status": "active",
    "access_scope": "GLOBAL"
  }
]

Get LLM Model Choices

Endpoint: GET /api/llm-models/choices

Description: Returns a simplified list of models suitable for populating UI dropdowns.

Authentication: User Token Required

Response 200 OK:

 Copy[
  {
    "model_id": "gpt-4.1-mini-2025-04-14",
    "name": "GPT-4o Mini",
    "provider": "openai"
  }
]

(Admin-only endpoints for creating, updating, and deleting LLM models also exist but require Superadmin privileges.)

6. Administration API

These endpoints are for platform management and require Superadmin privileges.

Base URL: /admin

Create a Solution

Endpoint: POST /admin/solutions

Description: Creates a top-level solution (e.g., "SynergyHub Medical").

Authentication: Superadmin Token Required

Request Body:

 Copy{
  "name": "SynergyHub for Healthcare",
  "description": "A solution tailored for medical professionals."
}

Response 201 Created: The full Solution object.

Create an Account

Endpoint: POST /admin/accounts

Description: Creates a customer account and links it to a solution and account type.

Authentication: Superadmin Token Required

Request Body:

 Copy{
  "name": "General Hospital",
  "account_type_id": "6650a3123b4c5d6e7f8a9b3a",
  "primary_solution_id": "6650a3123b4c5d6e7f8a9b0b"
}

Response 201 Created: The full Account object.

Add a User to an Account

Endpoint: POST /admin/accounts/<account_id>/members

Description: Grants a user membership and roles within a specific account.

Authentication: Superadmin Token Required

Request Body:

 Copy{
  "user_id": "6650a3123b4c5d6e7f8a9b0c",
  "roles": ["account_admin", "account_member"]
}

Response 200 OK: {"status": "success", "message": "User added to account."}

(This section also includes full CRUD for Solutions, Accounts, Groups, Account Types, Group Types, and managing user memberships in groups.)

6.1. Other Notable Endpoints

• Data Categories (/api/gen/data-categories): Manage categories for organizing data.
• Goals (/api/gen/goals): CRUD for user-specific goals.
• Logs (/api/logs): (Superadmin only) Access to activity and interaction logs.
• File Uploads (/api/gen/documents): A multi-step process for securely uploading files to Google Cloud Storage.
  1. POST /generate-upload-url: Client sends file metadata (name, type) and receives a signed URL.
  2. Client PUTs the file directly to the signed URL.
  3. POST /confirm-upload: Client notifies the backend that the upload is complete.