Workspace

Retrieve list of models

get

Retrieve List of Models

This endpoint allows authenticated users to retrieve a comprehensive list of available AI models, filtered by type and categorized based on accessibility and ownership.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To access model lists for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
page	PageEnum	Yes	Context of the request - "chat" for chat interface or other for management.
type	TypeModelEnum	No	Specific type of models to filter by.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Model Types Available

Type	Description
private	Models privately owned by the user
shared	Models shared with the user by other users
team	Models available to the user's team(s)
llm	Large Language Models available to the user
being verified	Models currently undergoing verification
public	Publicly available models
(none)	All available models combined

---

Responses

Status Code	Description
200	Success - Returns a list of models matching the requested criteria.
400	Bad Request - Acting user not in teams or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - Insufficient permissions to access the requested model list.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON array of model objects with the following structure:

[
  {
    "model_name": "model-identifier",
    "display_name": "User-Friendly Model Name",
    "description": "Model description and capabilities",
    "model_type": "private|shared|team|llm|public",
    "owner_email": "[email protected]",
    "encryption_type": "none|encrypted",
    "status": "active|verifying|inactive",
    "created_date": "2024-01-15",
    "last_updated": "2024-03-20"
  }
]

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Type-Based Filtering: Retrieves models based on the specified type parameter:

   • Private: User's personally owned models

   • Shared: Models shared with the user by others

   • Team: Models available to the user's team(s)

   • LLM: Large Language Models available to the user

   • Being Verified: Models undergoing verification

   • Public: Publicly available models

4. Context-Specific Processing: Adjusts results based on the page context (chat vs management)

5. Priority Sorting: Prioritizes specific models like "Understand Tech" in the results

6. Structured Formatting: Organizes the data into a standardized response format

---

Example Use Cases

• Chat Interface: User wants to see all available models for chatting

• Model Management: User wants to manage their private models and see shared/team models

• Model Discovery: User wants to explore public and LLM models available to them

---

Example Request

GET /api/v2/workspace/models?page=chat&type=private&[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

[
  {
    "model_name": "my-private-model",
    "display_name": "My Private Assistant",
    "description": "Custom trained on company documentation",
    "model_type": "private",
    "owner_email": "[email protected]",
    "encryption_type": "encrypted",
    "status": "active",
    "created_date": "2024-01-15",
    "last_updated": "2024-03-20"
  },
  {
    "model_name": "team-analysis-model",
    "display_name": "Data Analysis Assistant",
    "description": "Specialized in data analysis and visualization",
    "model_type": "team",
    "owner_email": "[email protected]",
    "encryption_type": "none",
    "status": "active",
    "created_date": "2024-02-10",
    "last_updated": "2024-03-15"
  },
  {
    "model_name": "understand-tech",
    "display_name": "Understand Tech",
    "description": "Advanced technical knowledge base",
    "model_type": "public",
    "owner_email": "[email protected]",
    "encryption_type": "none",
    "status": "active",
    "created_date": "2024-01-01",
    "last_updated": "2024-03-25"
  }
]

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

pagestring · enumRequiredPossible values:

typestring · enumOptionalPossible values:

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

get

/workspace/models

HTTPcURLJavaScriptPython

GET /api/v2/workspace/models?page=chat HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

[
  {
    "data_type": "",
    "description": "",
    "model_id": "",
    "model_name": "",
    "prompt_count": 0,
    "timestamp": "",
    "type": "",
    "user_email": ""
  }
]

Fetch Model Details by ID

get

Fetch Model Details by ID

This endpoint allows authenticated users to retrieve comprehensive details about a specific AI model by its unique identifier. It handles encrypted models by deriving decryption tokens from user-provided secrets.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To access model details for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
model_id	string	Yes	Unique identifier of the model to retrieve.

---

Query Parameters

Parameter Name	Type	Required	Description
secret	string	No	Encryption secret required for accessing encrypted models.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Returns comprehensive details about the requested model.
400	Bad Request - Model not found, missing secret for encrypted models, acting user not in teams, or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a detailed model object with the following structure:

{
  "model_name": "model-identifier",
  "date_of_creation": "2024-01-15 14:30:25",
  "timestamp": 1705339825,
  "status": "private",
  "doc_id": "document-identifier",
  "vectorstore_url": "https://vectorstore.url",
  "model_from": "source-platform",
  "api_key": "api-key-value",
  "description": "Model description and purpose",
  "model_url": "https://app.understand.tech?api_key=key&model_id=id&token=token",
  "language": "🇺🇸 English",
  "personality": "Professional",
  "tone": "Formal",
  "detail_level": "Adaptive Detail Level",
  "allow_public_info": "No",
  "response_language": "User Chosen Language",
  "show_references": "No",
  "document_urls": ["url1", "url2"],
  "custom_prompt": "Custom prompt text",
  "ai_model": "🇺🇸 OpenAI",
  "first_message": "Welcome message",
  "collect_email": false,
  "collect_phone": false,
  "hubspot_api_key": "",
  "data_type": "unstructured",
  "prompt1": "Prompt variant 1",
  "prompt2": "Prompt variant 2",
  "prompt3": "Prompt variant 3",
  "prompt4": "Prompt variant 4",
  "prompt5": "Prompt variant 5"
}

---

Technical Process

The endpoint performs the following complex operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Model Existence Check: Verifies the requested model exists in the database

4. Encryption Handling: For encrypted models:

   • Validates the presence of a secret parameter

   • Retrieves encryption salt from the database

   • Generates a secure token for model access

5. URL Construction: Builds the model access URL with appropriate parameters

6. Data Transformation: Formats and returns all model metadata in a structured response

---

Example Use Case

A user wants to inspect the detailed configuration of a specific model they own or have access to. For encrypted models, they provide their secret to generate an access token. The response includes all model metadata and a ready-to-use URL for accessing the model in the application.

---

Example Request

GET /api/v2/workspace/models/model_abc123?secret=my_encryption_secret&[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

{
  "model_name": "enterprise-knowledge-base",
  "date_of_creation": "2024-03-15 09:45:30",
  "timestamp": 1710495930,
  "status": "private",
  "doc_id": "model_abc123",
  "vectorstore_url": "https://vectorstore.example.com/123",
  "model_from": "custom-training",
  "api_key": "sk_1234567890abcdef",
  "description": "Enterprise knowledge base with company documentation",
  "model_url": "https://app.understand.tech?api_key=sk_1234567890abcdef&model_id=enterprise-knowledge-base&token=abc123token456",
  "language": "🇺🇸 English",
  "personality": "Professional",
  "tone": "Formal",
  "detail_level": "Detailed",
  "allow_public_info": "No",
  "response_language": "Same as Question",
  "show_references": "Yes",
  "document_urls": [
    "https://docs.company.com/handbook.pdf",
    "https://docs.company.com/procedures.docx"
  ],
  "custom_prompt": "You are a helpful assistant for Company Inc. employees...",
  "ai_model": "🇺🇸 OpenAI",
  "first_message": "Hello! How can I help you with Company Inc. information today?",
  "collect_email": true,
  "collect_phone": false,
  "hubspot_api_key": "hubspot_12345",
  "data_type": "structured",
  "prompt1": "Standard response prompt",
  "prompt2": "Detailed explanation prompt",
  "prompt3": "Quick summary prompt",
  "prompt4": "Technical deep dive prompt",
  "prompt5": "Executive summary prompt"
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

model_idstringRequired

Query parameters

secretany ofOptional

stringOptional

or

nullOptional

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

get

/workspace/models/{model_id}

HTTPcURLJavaScriptPython

GET /api/v2/workspace/models/{model_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

{
  "ai_model": "ai_model",
  "allow_public_info": "allow_public_info",
  "api_key": "api_key",
  "chat_button": "chat_button",
  "chat_color": "chat_color",
  "chat_icon": "chat_icon",
  "chat_theme": "chat_theme",
  "collect_email": "collect_email",
  "collect_phone": "collect_phone",
  "custom_prompt": "custom_prompt",
  "data_type": "data_type",
  "date_of_creation": "date_of_creation",
  "description": "description",
  "detail_level": "detail_level",
  "doc_id": "doc_id",
  "document_urls": [],
  "first_message": "first_message",
  "hubspot_api_key": "hubspot_api_key",
  "language": "language",
  "model_from": "model_from",
  "model_name": "model_name",
  "model_url": "model_url",
  "n8n_api_key": "n8n_api_key",
  "personality": "personality",
  "prompt1": "prompt1",
  "prompt2": "prompt2",
  "prompt3": "prompt3",
  "prompt4": "prompt4",
  "prompt5": "prompt5",
  "response_language": "response_language",
  "show_references": "show_references",
  "status": "status",
  "timestamp": "timestamp",
  "tone": "tone",
  "vectorstore_url": "vectorstore_url",
  "zoho_api_key": "zoho_api_key"
}

Delete a Model

delete

Delete Model

This endpoint allows authenticated users to permanently delete a specific AI model by its unique identifier. It handles model removal from the database and cache invalidation.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
model_id	string	Yes	Unique identifier of the model to delete.

---

Responses

Status Code	Description
200	Success - Model was successfully deleted. Returns confirmation message.
400	Bad Request - Error occurred during deletion process.
401	Unauthorized - Invalid or missing authentication token.
404	Not Found - The specified model ID does not exist.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Model deleted successfully"
}

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials

2. Model Existence Check: Confirms the specified model ID exists in the database

3. Model Identification: Retrieves the model name for cache invalidation purposes

4. Database Deletion: Permanently removes the model document from Firestore

5. Cache Invalidation: Clears any cached data related to the deleted model

6. Confirmation: Returns a success message in the user's preferred language

---

Security Considerations

• Permanent Deletion: This action cannot be undone - the model is permanently removed

• Authorization: Users can only delete models they have permission to access

• Cache Consistency: Ensures cached model data is invalidated to prevent stale references

• Error Handling: Provides appropriate error messages for different failure scenarios

---

Example Use Case

A user wants to remove a model that is no longer needed or was created incorrectly. They provide the model's unique identifier, and the system permanently deletes the model from the database and ensures all cached references are cleared.

---

Example Request

DELETE /api/v2/workspace/models/model_abc123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

{
  "detail": "Model deleted successfully"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Model not found	404	"Model not found"
Database error	400	"An error occurred"
Invalid authentication	401	"Unauthorized"
Invalid model ID format	422	"Validation error"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

model_idstringRequired

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

delete

/workspace/models/{model_id}

HTTPcURLJavaScriptPython

DELETE /api/v2/workspace/models/{model_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Fetch prompts monitoring

post

Fetch Prompts Monitoring

This endpoint allows authenticated users to retrieve and monitor prompt-response interactions for a specific AI model. It handles decryption of encrypted conversations using appropriate keys based on the encryption mode.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To access monitoring data for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
model_id	string	Yes	Unique identifier of the model to monitor.

---

Query Parameters

Parameter Name	Type	Required	Description
model_name	string	Yes	Name of the model to fetch monitoring data for.
limit	integer	No	Maximum number of prompt-response pairs to return.
secret	string	No	Encryption secret required for decrypting encrypted model conversations.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Returns monitoring data with decrypted prompts, responses, and feedback.
400	Bad Request - Model not found, missing secret for encrypted models, acting user not in teams, or decryption errors.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON array with the following structure:

[
  {
    "prompt": "User's original question",
    "response": "Model's generated response",
    "time": 1705339825,
    "feedback": "User feedback text"
  }
]

---

Technical Process

The endpoint performs the following complex operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Model Verification: Confirms the specified model exists and retrieves its encryption settings

4. Key Derivation: For encrypted models, derives appropriate decryption keys:

   • Key B Mode: Derives Key B from user secret for direct decryption

   • Owner Public Key Mode: Uses ephemeral key exchange for decryption

5. Data Retrieval: Fetches prompt-response documents in descending chronological order

6. Decryption Processing: Applies appropriate decryption based on encryption mode:

   • Plaintext: Returns data without decryption

7. Feedback Correlation: Matches and decrypts user feedback using document IDs

8. Structured Response: Returns decrypted data in a standardized format

---

Encryption Modes Supported

Encryption Mode	Description	Secret Required
key_b	Direct encryption using Key B derived from user secret	Yes
owner_pub_key	Ephemeral key exchange using owner's public key	Yes
None (plaintext)	No encryption - data stored in clear text	No

---

Example Use Case

A model owner wants to review recent conversations with their AI model to monitor performance and user feedback. For encrypted models, they provide their secret to decrypt the conversations. The system returns the most recent interactions with decrypted prompts, responses, and any associated feedback.

---

Example Request

POST /api/v2/workspace/models/model_abc123/prompts-monitoring?model_name=enterprise-assistant&limit=10&secret=my_encryption_secret&[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

[
  {
    "prompt": "How do I reset my password?",
    "response": "You can reset your password by visiting the account settings page and clicking 'Forgot Password'.",
    "time": 1710495930,
    "feedback": "Helpful response, solved my issue quickly"
  },
  {
    "prompt": "What are the company's security policies?",
    "response": "Our security policies include mandatory 2FA, regular password changes, and encrypted data storage. Specific details are available in the employee handbook.",
    "time": 1710489130,
    "feedback": ""
  },
  {
    "prompt": "How to request vacation time?",
    "response": "Vacation requests can be submitted through the HR portal with at least two weeks notice for approval.",
    "time": 1710482530,
    "feedback": "The process was clearer after this explanation"
  }
]

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

model_idstringRequired

Query parameters

model_namestringRequired

limitany ofOptional

integerOptional

or

nullOptional

secretany ofOptional

stringOptional

or

nullOptional

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany of

or

nullOptional

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/workspace/models/{model_id}/prompts-monitoring

HTTPcURLJavaScriptPython

POST /api/v2/workspace/models/{model_id}/prompts-monitoring?model_name=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

[
  {
    "feedback": "",
    "prompt": "",
    "response": "",
    "time": ""
  }
]

Get User's Team

get

Get User's Teams

This endpoint allows authenticated users to retrieve comprehensive information about all teams they belong to, including team details, member information, and invitation statuses.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To access team information for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Returns comprehensive team information including members and their statuses.
400	Bad Request - Acting user not in teams or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON object with the following structure:

{
  "teams_count": 3,
  "teams": [
    {
      "team_id": "team-identifier-1",
      "team_name": "Development Team",
      "is_external": false,
      "members": [
        {
          "member_email": "[email protected]",
          "member_status": "accepted",
          "member_role": "owner"
        },
        {
          "member_email": "[email protected]",
          "member_status": "accepted",
          "member_role": "member"
        },
        {
          "member_email": "[email protected]",
          "member_status": "pending",
          "member_role": "member"
        }
      ]
    }
  ]
}

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Team Count Retrieval: Fetches the total number of teams the user belongs to from user document

4. Team Data Collection: Retrieves all teams where the user is a member

5. Member Enumeration: Identifies all members within each team with their roles

6. Invitation Status: Checks for pending invitations to include in member list

7. Role Assignment: Determines each member's role within the team

8. External Team Filtering: Handles special logic for external teams and owner roles

9. Structured Formatting: Organizes the data into a standardized response format

---

Member Status Types

Status	Description
accepted	User has accepted the team invitation and is an active member
pending	User has been invited but has not yet accepted the invitation

---

Member Role Types

Role	Description
owner	Has full administrative privileges over the team
member	Standard team member with appropriate access rights

---

Example Use Case

A user wants to see all teams they belong to, including detailed information about each team's members, their roles, and any pending invitations. This helps users understand their team structure and manage team memberships.

---

Example Request

GET /api/v2/workspace/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

{
  "teams_count": 2,
  "teams": [
    {
      "team_id": "team_abc123",
      "team_name": "Development Team",
      "is_external": false,
      "members": [
        {
          "member_email": "[email protected]",
          "member_status": "accepted",
          "member_role": "owner"
        },
        {
          "member_email": "[email protected]",
          "member_status": "accepted",
          "member_role": "member"
        },
        {
          "member_email": "[email protected]",
          "member_status": "pending",
          "member_role": "member"
        }
      ]
    },
    {
      "team_id": "team_def456",
      "team_name": "Data Analysis Team",
      "is_external": true,
      "members": [
        {
          "member_email": "[email protected]",
          "member_status": "accepted",
          "member_role": "owner"
        },
        {
          "member_email": "[email protected]",
          "member_status": "accepted",
          "member_role": "member"
        }
      ]
    }
  ]
}

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

get

/workspace/teams

HTTPcURLJavaScriptPython

GET /api/v2/workspace/teams HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

{
  "teams": [
    {
      "members": [
        {
          "member_email": "",
          "member_role": "",
          "member_status": ""
        }
      ],
      "team_id": "",
      "team_name": ""
    }
  ],
  "teams_count": 0
}

Create a New Team

post

Create a New Team

This endpoint allows authenticated users to create a new team with specified parameters. It handles team creation, ownership assignment, and team limit validation.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To create a team for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
team_name	string	Yes	Name of the new team to create.
is_external	boolean	Yes	Whether the team is external (true) or internal (false).
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Team was successfully created. Returns confirmation message.
400	Bad Request - Team creation not authorized (limit reached), acting user not in teams, or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Team 'Team Name' created successfully"
}

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Team Limit Validation: Checks if the user has reached their maximum allowed team count

4. Team Creation: Creates a new team document in Firestore with:

   • Team name and external flag

   • Owner assignment

   • Initial member list (containing the creator)

   • Role assignment (owner role for creator)

5. Success Response: Returns a confirmation message in the user's preferred language

---

Team Structure

Upon creation, each team includes:

• team_name: The specified name for the team

• is_external: Boolean indicating if the team is external

• owner: Email of the team creator/owner

• members: Array containing the owner's email as initial member

• roles: Dictionary mapping the owner to 'owner' role

---

Limit Validation

The system checks:

1. Current number of teams owned by the user

2. Maximum allowed teams from user's profile

3. Prevents creation if current teams >= allowed limit + 1

---

Example Use Case

A user wants to create a new team for a project. They specify the team name and whether it's an external team (for collaborating with outside partners). The system validates they haven't exceeded their team limit, creates the team, and assigns them as the owner.

---

Example Request

POST /api/v2/workspace/team?team_name=Project%20Alpha&is_external=true&[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

{
  "detail": "Team 'Project Alpha' created successfully"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Team limit reached	400	"Team creation not authorized"
Invalid authentication	401	"Unauthorized"
Acting user not in teams	400	"Acting user not in your teams"
Invalid parameters	422	"Validation error"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

team_namestringRequired

is_externalbooleanRequired

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/workspace/team

HTTPcURLJavaScriptPython

POST /api/v2/workspace/team?team_name=text&is_external=true HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Update Team Member's Role

post

Update Team Member's Role

This endpoint allows team owners to update the role of a member within a specific team. It provides role management capabilities for team administration.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
team_id	string	Yes	Unique identifier of the team.

---

Form Parameters

Parameter Name	Type	Required	Description
member	string	Yes	Email address of the team member whose role is being updated.
new_role	RoleEnum	Yes	New role to assign to the team member.

---

Available Roles (RoleEnum)

Role	Description
owner	Has full administrative privileges over the team
member	Standard team member with appropriate access rights

---

Responses

Status Code	Description
200	Success - Member's role was successfully updated. Returns confirmation message.
400	Bad Request - Error occurred during the update process.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data or role value.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Role for [email protected] updated to owner in team team_abc123."
}

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials

2. Role Validation: Ensures the new role is a valid value from RoleEnum

3. Database Update: Updates the member's role in the specified team document

4. Key Sanitization: Properly formats the member email for Firestore key storage

5. Confirmation: Returns a success message in the user's preferred language

---

Security Considerations

• Authorization: Typically only team owners should have permission to update roles

• Input Validation: Validates both team ID and member email format

• Role Integrity: Ensures only valid role values are accepted

• Error Handling: Provides appropriate error messages without exposing system details

---

Example Use Case

A team owner wants to promote a member to owner status or change roles within their team. They specify the team ID, member email, and new role. The system updates the role in the database and returns a confirmation message.

---

Example Request

POST /api/v2/workspace/teams/team_abc123/member/role HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/x-www-form-urlencoded

[email protected]&new_role=owner

---

Example Response

{
  "detail": "Role for [email protected] updated to owner in team team_abc123."
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Invalid team ID	400	"An error occurred"
Invalid member email	400	"An error occurred"
Invalid role value	422	"Validation error"
Database update failure	400	"An error occurred"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

team_idanyRequired

Query parameters

memberanyRequired

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/x-www-form-urlencoded

new_rolestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/workspace/teams/{team_id}/member/role

HTTPcURLJavaScriptPython

POST /api/v2/workspace/teams/{team_id}/member/role?member=null HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 20

"new_role='admin'"

No content

Add a Team Member to a Team

post

Add a Team Member to a Team

This endpoint allows team owners to add new members to a specific team. It handles email validation, subscription checks, invitation management, and automatic provisioning with comprehensive team membership validation.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To add members for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
team_id	string	Yes	Unique identifier of the team.

---

Query Parameters

Parameter Name	Type	Required	Description
membre_email	string	Yes	Email address of the member to add to the team.
auto_provision	boolean	No	Whether to automatically provision the user without requiring invitation acceptance.
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Member was successfully added or invited. Returns appropriate confirmation message.
400	Bad Request - Various validation errors including email format, team limits, subscription conflicts, or existing memberships.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

For auto_provision=true:

{
  "detail": "Invitation accepted for team team_abc123"
}

For auto_provision=false or omitted:

{
  "detail": "Invitation sent successfully to [email protected]"
}

---

Technical Process

The endpoint performs the following comprehensive validation and operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Email Validation: Ensures the provided email address has a valid format

4. Team Existence Check: Confirms the specified team exists

5. Team Capacity Validation: Ensures the team hasn't reached the 10-member limit

6. Subscription Check: Verifies the user doesn't already have a premium subscription

7. Existing Membership Check: Ensures the user isn't already in another team or isn't a team owner

8. Duplicate Invitation Check: Prevents duplicate pending invitations

9. Role Assignment: Assigns appropriate role (admin/member) based on team type and ownership

10. User Provisioning: Either automatically provisions the user or sends an invitation email

---

Validation Checks

Check Type	Error Message
Invalid email format	"Invalid email format"
Team not found	"Team not found"
Team member limit reached	"Team has reached maximum users limit"
User already subscribed	"User [email protected] already has a subscription"
User already in team	"User [email protected] is already part of a team"
Existing invitation	"An invitation already exists for [email protected]"

---

Auto Provisioning Behavior

auto_provision	Action
true	User is immediately added to team, subscription updated, invitation marked as accepted
false or omitted	Invitation is sent via email, status set to pending

---

Example Use Cases

• Team Expansion: Team owner wants to add a new member with automatic provisioning

• External Collaboration: Adding external partners to a team with proper invitation workflow

• Team Management: Managing team membership with appropriate role assignments

---

Example Request

POST /api/v2/workspace/teams/team_abc123/[email protected]&auto_provision=true&[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

{
  "detail": "Invitation accepted for team team_abc123"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Invalid email format	400	"Invalid email format"
Team not found	400	"Team not found"
Team at capacity	400	"Team has reached maximum users limit"
User already subscribed	400	"User [email protected] already has a subscription"
Duplicate invitation	400	"An invitation already exists for [email protected]"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

team_idstringRequired

Query parameters

membre_emailstringRequired

auto_provisionany ofOptional

booleanOptional

or

nullOptional

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/workspace/teams/{team_id}/member

HTTPcURLJavaScriptPython

POST /api/v2/workspace/teams/{team_id}/member?membre_email=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Remove Team Member

delete

Remove Team Member

This endpoint allows team owners to remove a member from a specific team. It performs comprehensive cleanup including removing the member from the team, deleting pending invitations, and updating the member's subscription plan.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
team_id	string	Yes	Unique identifier of the team.

---

Query Parameters

Parameter Name	Type	Required	Description
membre_email	string	Yes	Email address of the member to remove from the team.

---

Responses

Status Code	Description
200	Success - Member was successfully removed from the team. Returns confirmation message.
400	Bad Request - Error occurred during the removal process or subscription plan update.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Member [email protected] successfully removed from team team_abc123."
}

---

Technical Process

The endpoint performs the following comprehensive cleanup operations:

1. Authentication Validation: Verifies user credentials

2. Team Member Removal: Removes the member from the team's members array

3. Role Cleanup: Deletes the member's role entry from the team

4. Invitation Cleanup: Removes any pending invitations for the member in this team

5. Subscription Plan Update: Downgrades the member's subscription to "Freemium"

6. Confirmation: Returns a success message in the user's preferred language

---

Cleanup Operations

Operation	Description
Member Removal	Removes email from team members array
Role Deletion	Deletes role assignment for the member
Invitation Cleanup	Removes pending invitations for the member
Subscription Update	Resets user subscription to Freemium plan

---

Security Considerations

• Authorization: Typically only team owners should have permission to remove members

• Data Integrity: Ensures complete cleanup of member-related data

• Subscription Management: Automatically manages subscription changes

• Error Handling: Provides appropriate error messages for different failure scenarios

---

Example Use Case

A team owner needs to remove a member from their team. The system not only removes the member from the team but also cleans up any pending invitations and adjusts the member's subscription plan accordingly.

---

Example Request

DELETE /api/v2/workspace/teams/team_abc123/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

{
  "detail": "Member [email protected] successfully removed from team team_abc123."
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Invalid team ID	400	"An error occurred"
Invalid member email	400	"An error occurred"
Subscription plan update failure	400	"Error updating subscription plan for [email protected]"
Database operation failure	400	"An error occurred"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

team_idstringRequired

Query parameters

membre_emailstringRequired

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

delete

/workspace/teams/{team_id}/member

HTTPcURLJavaScriptPython

DELETE /api/v2/workspace/teams/{team_id}/member?membre_email=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Check for Pending Workspace Invitations

get

Check for Pending Workspace Invitations

This endpoint allows users to check if they have any pending invitations to join workspace teams. It handles authentication, external user validation, and returns a list of pending invitations with team details.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To check invitations on behalf of an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
team_id	string	Yes	Unique identifier of the team.

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Returns a list of pending invitations or an empty array if none exist.
400	Bad Request - Various validation errors including team not found or permission issues.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

[
  {
    "invitation_id": "inv_abc123",
    "team_id": "team_abc123",
    "team_name": "Development Team",
    "is_external": false,
    "status": "pending"
  }
]

---

Technical Process

The endpoint performs the following comprehensive validation and operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Team Existence Check: Confirms the specified team exists

4. Invitation Query: Retrieves all pending invitations for the authenticated user

5. Team Data Enrichment: Fetches additional team information for each invitation

6. Response Formatting: Structures the response according to the InvitationSchema

---

Validation Checks

Check Type	Error Message
Team not found	"Team not found"
Acting user not in owner's teams	"User {acting_user_email} is not in your teams"
Database error	"An error occurred while processing your request"

---

Example Use Cases

• Invitation Management: Users can check their pending invitations to join teams

• External Collaboration: External users can verify their pending team invitations

• Team Onboarding: New members can confirm they've received team invitations

---

Example Request

GET /api/v2/workspace/teams/team_abc123/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

[
  {
    "invitation_id": "inv_abc123def456",
    "team_id": "team_abc123",
    "team_name": "Marketing Team",
    "is_external": true,
    "status": "pending"
  },
  {
    "invitation_id": "inv_def456ghi789",
    "team_id": "team_def456",
    "team_name": "Development Team",
    "is_external": false,
    "status": "pending"
  }
]

---

Error Scenarios

Scenario	HTTP Status	Error Message
Team not found	400	"Team not found"
Acting user not authorized	400	"User [email protected] is not in your teams"
Database error	400	"An error occurred while processing your request"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

team_idstringRequired

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

get

/workspace/teams/{team_id}/invitations

HTTPcURLJavaScriptPython

GET /api/v2/workspace/teams/{team_id}/invitations HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

[
  {
    "invitation_id": "",
    "status": "",
    "team_id": "",
    "team_name": ""
  }
]

Accept or Refuse a Workspace Invitation

post

Accept or Refuse a Workspace Invitation

This endpoint allows users to accept or refuse pending invitations to join workspace teams. It handles authentication, external user validation, team membership updates, and subscription plan synchronization.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To respond to invitations on behalf of an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").
Content-Type	string	Yes	Must be application/x-www-form-urlencoded for form data submission.

---

Path Parameters

Parameter Name	Type	Required	Description
team_id	string	Yes	Unique identifier of the team.
invitation_id	string	Yes	Unique identifier of the invitation.

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Form Parameters

Parameter Name	Type	Required	Description
response_type	responseTypeInvitationEnum	Yes	The response to the invitation: accept or refuse.

---

Responses

Status Code	Description
200	Success - Invitation was successfully accepted or refused. Returns appropriate confirmation message.
400	Bad Request - Various validation errors including invalid response type or permission issues.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

For accepted invitation:

{
  "detail": "Invitation accepted for team team_abc123"
}

For refused invitation:

{
  "detail": "Invitation rejected for team team_abc123"
}

---

Technical Process

The endpoint performs the following comprehensive validation and operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Response Type Validation: Ensures the response type is either 'accept' or 'refuse'

4. Team Data Retrieval: Fetches team information including roles and owner details

5. Invitation Processing:

   • For acceptance: Adds user to team, updates roles, marks invitation as accepted, syncs subscription plan

   • For refusal: Deletes the invitation from the system

6. Subscription Synchronization: Updates user's subscription plan to match team owner's plan

---

Validation Checks

Check Type	Error Message
Invalid response type	"Invalid response type"
Acting user not in owner's teams	"User {acting_user_email} is not in your teams"
Database error	"An error occurred while processing your request"

---

Acceptance Behavior

When a user accepts an invitation:

• User is added to the team members list

• User's role is set according to team configuration

• Invitation status is updated to 'accepted'

• User's subscription plan is synchronized with team owner's plan

• User's external status is set according to team type

---

Refusal Behavior

When a user refuses an invitation:

• The invitation is permanently deleted from the system

• No changes are made to team membership or user subscription

---

Example Use Cases

• Team Joining: User accepts an invitation to join a collaborative workspace

• Invitation Management: User declines an unwanted team invitation

• External Collaboration: External partners respond to team invitations

• Subscription Synchronization: Automatic plan alignment when joining teams

---

Example Request

Accept an invitation:

POST /api/v2/workspace/teams/team_abc123/inv_123456/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/x-www-form-urlencoded

response_type=accept

Refuse an invitation:

POST /api/v2/workspace/teams/team_abc123/inv_123456/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/x-www-form-urlencoded

response_type=refuse

---

Example Response

For acceptance:

{
  "detail": "Invitation accepted for team team_abc123"
}

For refusal:

{
  "detail": "Invitation rejected for team team_abc123"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Invalid response type	400	"Invalid response type"
Acting user not authorized	400	"User [email protected] is not in your teams"
Database error	400	"An error occurred while processing your request"

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

team_idstringRequired

invitation_idstringRequired

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

application/x-www-form-urlencoded

response_typestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

post

/workspace/teams/{team_id}/{invitation_id}/response

HTTPcURLJavaScriptPython

POST /api/v2/workspace/teams/{team_id}/{invitation_id}/response HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 26

"response_type='accept'"

No content

Delete a Team

delete

Delete a Team

This endpoint allows team owners to permanently delete a team from the workspace. It handles team deletion, user subscription updates, and external status management for all team members.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
team_id	string	Yes	Unique identifier of the team to delete.

---

Responses

Status Code	Description
200	Success - Team was successfully deleted and user subscriptions were updated.
400	Bad Request - Various validation errors including team not found or database issues.
401	Unauthorized - Invalid or missing authentication token.
404	Not Found - The specified team does not exist.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Team deleted successfully"
}

---

Technical Process

The endpoint performs the following comprehensive operations:

1. Authentication Validation: Verifies user credentials and permissions

2. Team Existence Check: Confirms the specified team exists before deletion

3. Team Data Retrieval: Extracts team information including members list and external status

4. Team Deletion: Permanently removes the team from the database

5. User Subscription Updates:

   • Sets all team members' subscription plan to "Freemium"

   • Removes external status flag if the team was external

6. Cleanup Completion: Returns success confirmation message

---

Post-Deletion User Updates

User Attribute	Update Action
subscription_plan	Set to "Freemium" for all former team members
external	Set to false if the deleted team was external (is_external == true)

---

Validation Checks

Check Type	Error Message
Team not found	"Team not found"
Database error	"An error occurred while processing your request"

---

Deletion Impact

• Team Data: Permanently removed from the 'teams' collection

• Team Members: All users lose team membership and revert to Freemium subscription

• External Users: Users from external teams have their external status removed

• Invitations: All pending invitations for this team become invalid (should be handled separately)

---

Example Use Cases

• Team Dissolution: Team owner decides to disband the team permanently

• Organization Restructuring: Teams are consolidated or reorganized

• Project Completion: Temporary teams are deleted after project completion

• Cleanup Operations: Removing inactive or obsolete teams from the system

---

Example Request

DELETE /api/v2/workspace/teams/team_abc123 HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

{
  "detail": "Team deleted successfully"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Team not found	404	"Team not found"
Database connection error	400	"An error occurred while processing your request"
Permission denied	401	"Unauthorized"

---

Security Considerations

• Only team owners or users with appropriate permissions should be able to delete teams

• The operation is irreversible - deleted teams cannot be recovered

• All user data updates are performed atomically to maintain data consistency

• External status cleanup prevents users from retaining inappropriate access privileges

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

team_idstringRequired

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

delete

/workspace/teams/{team_id}

HTTPcURLJavaScriptPython

DELETE /api/v2/workspace/teams/{team_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Updates the status of a specified model while handling encryption changes.

post

Update Model Status

This endpoint allows users to update the status of a specified AI model while handling encryption changes based on the new status. It manages transitions between private, team, and public statuses with appropriate encryption/decryption operations.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To update model status on behalf of an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").
Content-Type	string	Yes	Must be application/x-www-form-urlencoded for form data submission.

---

Path Parameters

Parameter Name	Type	Required	Description
model_id	string	Yes	Unique identifier of the model to update.

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Form Parameters

Parameter Name	Type	Required	Description
new_status	string	Yes	The new status for the model: public, team, or private.
secret	string	No	Passphrase required for encryption/decryption operations when applicable.

---

Responses

Status Code	Description
200	Success - Model status was successfully updated with appropriate encryption handling.
400	Bad Request - Various validation errors including model not found, invalid status, or missing secret.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Status updated successfully"
}

---

Technical Process

The endpoint performs the following comprehensive validation and operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Model Existence Check: Confirms the specified model exists

4. Subscription Validation: Checks user's subscription plan and encryption capabilities

5. Encryption Key Verification: Validates user has appropriate encryption keys

6. Status Transition Handling:

   • To Public: Decrypts if encrypted, sets status to "being verified", notifies admin

   • To Team: Encrypts with team key if Enterprise user

   • To Private: Re-encrypts for user if previously public/team

7. Vectorstore Operations: Performs encryption/decryption as needed based on status change

---

Encryption Requirements

Status Change	Encryption Requirement
Encrypted → Public	Secret required for decryption
Public → Encrypted	Secret required for encryption
Team → Encrypted	Secret required for re-encryption

---

Subscription Requirements

Operation	Required Plan
Encryption/Decryption	Enterprise
Team encryption	Enterprise

---

Validation Checks

Check Type	Error Message
Model not found	"Model not found"
Invalid status	"Invalid status"
Secret required	"Secret required for Enterprise users"
Acting user not authorized	"User {acting_user_email} is not in your teams"
Insufficient subscription	"Enterprise subscription required for encryption"

---

Status Transition Behavior

From → To	Action
Any → Public	Decrypts if encrypted, sets to "being verified", notifies admin
Public → Private	Encrypts with user key (Enterprise only)
Team → Private	Re-encrypts with user key (Enterprise only)
Private → Team	Encrypts with team key (Enterprise only)

---

Example Use Cases

• Model Publication: User wants to make a private model publicly available

• Team Collaboration: Moving a model to team-accessible status with team encryption

• Access Restriction: Making a public or team model private again

• Enterprise Security: Managing encryption for sensitive AI models

---

Example Requests

Make model public:

POST /api/v2/workspace/models/model_abc123/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/x-www-form-urlencoded

new_status=public&secret=my_encryption_passphrase

Make model private:

POST /api/v2/workspace/models/model_abc123/status HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/x-www-form-urlencoded

new_status=private&secret=my_encryption_passphrase

Make model team-accessible:

POST /api/v2/workspace/models/model_abc123/status HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US
Content-Type: application/x-www-form-urlencoded

new_status=team&secret=my_encryption_passphrase

---

Example Responses

For public submission:

{
  "detail": "Model submitted for public verification"
}

For status update:

{
  "detail": "Status updated to team successfully"
}

---

Error Scenarios

Scenario	HTTP Status	Error Message
Model not found	400	"Model not found"
Invalid status	400	"Invalid status"
Secret required	400	"Secret required for Enterprise users"
Acting user not authorized	400	"User [email protected] is not in your teams"
Database error	400	"An error occurred while processing your request"

---

Security Considerations

• Encryption operations require Enterprise subscription

• Secret passphrase is mandatory for encryption/decryption operations

• Public models are stored in plaintext without encryption

• Team models use team-based encryption keys

• Private models use user-specific encryption keys

• Admin notification is sent for public model submissions

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

model_idstringRequired

Query parameters

new_statusstringRequired

secretany ofOptional

stringOptional

or

nullOptional

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

401

Unauthorized

422

Validation Error

post

/workspace/models/{model_id}/status

HTTPcURLJavaScriptPython

POST /api/v2/workspace/models/{model_id}/status?new_status=text HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Get all teams with members and all their API keys with details

get

Get Teams Members API Keys

This endpoint allows authenticated users to retrieve comprehensive information about all teams they belong to, including team members and their associated API keys with detailed metadata.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

• External Usage Requirement: To access team information for an external user, the API key used for authentication must itself be configured for external usage (i.e., accept_external_client must be true).

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Query Parameters

Parameter Name	Type	Required	Description
acting_user_email	string	No	Email of the user acting on the owner's behalf (for external usage). Requires the authenticating API key to have external usage enabled.

---

Responses

Status Code	Description
200	Success - Returns a comprehensive list of teams, members, and their API key details.
400	Bad Request - Acting user not in teams or other validation errors.
401	Unauthorized - Invalid or missing authentication token.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON array with the following structure:

[
  {
    "team_id": "team-identifier",
    "team_name": "Team Name",
    "email_member": "[email protected]",
    "api_key_member": "api-key-value",
    "api_key_name": "API Key Name",
    "expiration_date": "2024-12-31"
  }
]

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials and external usage permissions

2. Team Membership Check: Validates that acting users are part of the owner's teams for external usage

3. Team Retrieval: Fetches all teams where the user is a member

4. Member Enumeration: Identifies all members within each team

5. API Key Lookup: Retrieves all active API keys for each team member

6. Expiration Validation: Checks API key validity based on expiration dates

7. Structured Formatting: Organizes the data into a standardized response format

---

Data Structure Details

• One Entry Per API Key: Each member can have multiple API keys, so there will be one entry per API key

• Active Keys Only: Only returns API keys that haven't expired

• Complete Coverage: Includes entries for members without API keys (with null values)

• Team Context: Provides team identification for organizational context

---

Example Use Case

A team manager wants to review all API keys used by members of their teams to ensure security compliance and monitor key expiration. They can see which team members have active keys, when they expire, and identify any members who need to generate new keys.

---

Example Request

GET /api/v2/workspace/[email protected] HTTP/1.1
Host: api.example.com
Authorization: Bearer <USER_JWT_TOKEN>
accept_language: en-US

---

Example Response

[
  {
    "team_id": "team_abc123",
    "team_name": "Development Team",
    "email_member": "[email protected]",
    "api_key_member": "sk_1234567890abcdef",
    "api_key_name": "Development API Key",
    "expiration_date": "2024-12-31"
  },
  {
    "team_id": "team_abc123",
    "team_name": "Development Team",
    "email_member": "[email protected]",
    "api_key_member": "sk_0987654321abcdef",
    "api_key_name": "Testing Key",
    "expiration_date": "2024-06-30"
  },
  {
    "team_id": "team_def456",
    "team_name": "Data Science Team",
    "email_member": "[email protected]",
    "api_key_member": null,
    "api_key_name": null,
    "expiration_date": null
  }
]

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

acting_user_emailstringOptional

Email of the end user initiating this action

Header parameters

accept-languagestring · enumRequiredPossible values:

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

422

Validation Error

application/json

get

/workspace/teams-members-api-keys

HTTPcURLJavaScriptPython

GET /api/v2/workspace/teams-members-api-keys HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Accept: */*

No content

Update an existing AI model asynchronously

put

Update Model Settings

This endpoint allows authenticated users to update the configuration and appearance settings of an existing AI model. It supports customization of chat interface elements, visual themes, and functional behaviors.

---

Authentication

• Type: Bearer Token

• Required: Yes

• Header: Authorization: Bearer <JWT_TOKEN>

• Dependency: Depends(APIKeyBearer())

---

Request Headers

Header Name	Type	Required	Description
accept_language	LanguageEnum	Yes	Specifies the preferred language for response messages (e.g., "fr-FR").

---

Path Parameters

Parameter Name	Type	Required	Description
model_id	string	Yes	Unique identifier of the model to update.

---

Form Data Parameters

Parameter Name	Type	Required	Description
chat_color	string	No	Primary color for the chat interface.
chat_theme	string	No	Visual theme applied to the chat widget.
chat_icon_file	string	No	Empty string to remove existing chat icon.
chat_icon	UploadFile	No	New chat icon file (PNG or SVG format).
chat_button_file	string	No	Empty string to remove existing chat button.
chat_button	UploadFile	No	New chat button file (PNG or SVG format).
welcome_message	string	No	Initial message displayed when chat starts.
model_description	string	No	Description of the AI model.
language_toggle	boolean	No	Enable/disable language switching feature.
first_bot_message	string	No	First message sent by the bot in conversation.
conversation_header	string	No	Header text displayed in chat conversations.
widget_position	string	No	Position of the chat widget on screen.
chat_height	float	No	Height of the chat window in pixels.
chat_width	float	No	Width of the chat window in pixels.
button_text	string	No	Text displayed on the chat button.
button_color	string	No	Background color of the chat button.
text_color	string	No	Color of text in the chat interface.
can_download_chat_messages	boolean	No	Enable/disable chat message download capability.
primary_chat_color	string	No	Primary color scheme for chat elements.

---

Responses

Status Code	Description
200	Success - Model settings updated successfully.
400	Bad Request - Model not found, file upload errors, or other validation failures.
401	Unauthorized - Invalid or missing authentication token.
403	Forbidden - User lacks permission to update model settings.
422	Validation Error - The request contains invalid data.

---

Response Format (JSON)

The endpoint returns a JSON response with the following structure:

{
  "detail": "Settings updated successfully"
}

---

Technical Process

The endpoint performs the following operations:

1. Authentication Validation: Verifies user credentials and permissions

2. Model Verification: Confirms the specified model exists in the database

3. Field Processing: Updates individual settings fields only when provided

4. File Upload Handling:

   • Validates file formats (PNG/SVG only)

---

File Upload Specifications

File Type	Supported Formats	Storage Location	Field Names
Chat Icon	PNG, SVG	chat_icons/	chat_icon, chat_icon_file
Chat Button	PNG, SVG	chat_buttons/	chat_button, chat_button_file

---

Example Use Case

A model administrator wants to customize their AI assistant's appearance and behavior. They update the chat color scheme, upload a new brand icon, modify the welcome message, and enable the language toggle feature. The system processes these changes asynchronously and confirms successful update.

---

Example Request

curl -X 'PUT'   'http://127.0.0.1:8000/api/v2/model/settings/Rj8ohpeobQHn2KRWmVMj'   -H 'accept: application/json'   -H 'accept-language: en-US'   -H 'Authorization: Bearer 70a9d540-ae0e-4da4-b168-8d741f5384da'   -H 'Content-Type: multipart/form-data'   -F 'first_bot_message=Aske me any question about **Notes de Frais**'   -F 'conversation_header=Conversation with **Notes de Frais**'   -F 'welcome_message=Bienvenue! Je réponds à vos questions sur nos règlements intérieurs, politique de note de frais'   -F 'can_download_chat_messages=true'   -F 'language_toggle=false'

---

Example Response

{
  "detail": "Settings updated successfully"
}

---

Authorizations

APIKeyBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

model_idstringRequired

Header parameters

accept-languagestring · enumRequiredPossible values:

Body

multipart/form-data

chat_colorany ofOptional

stringOptional

or

nullOptional

chat_themeany ofOptional

stringOptional

or

nullOptional

chat_icon_fileany ofOptional

stringOptional

or

nullOptional

chat_iconany ofOptional

string · binaryOptional

or

nullOptional

chat_button_fileany ofOptional

stringOptional

or

nullOptional

chat_buttonany ofOptional

string · binaryOptional

or

nullOptional

welcome_messageany ofOptional

stringOptional

or

nullOptional

model_descriptionany ofOptional

stringOptional

or

nullOptional

language_toggleany ofOptionalDefault: false

booleanOptional

or

nullOptional

first_bot_messageany ofOptional

stringOptional

or

nullOptional

conversation_headerany ofOptional

stringOptional

or

nullOptional

widget_positionany ofOptional

stringOptional

or

nullOptional

chat_heightany ofOptional

numberOptional

or

nullOptional

chat_widthany ofOptional

numberOptional

or

nullOptional

button_textany ofOptional

stringOptional

or

nullOptional

button_colorany ofOptional

stringOptional

or

nullOptional

text_colorany ofOptional

stringOptional

or

nullOptional

can_download_chat_messagesany ofOptionalDefault: true

booleanOptional

or

nullOptional

primary_chat_colorany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Responseany

400

Bad Request

application/json

401

Unauthorized

application/json

403

Error: Forbidden

application/json

422

Validation Error

application/json

put

/model/settings/{model_id}

HTTPcURLJavaScriptPython

PUT /api/v2/model/settings/{model_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
accept-language: en-US
Content-Type: multipart/form-data
Accept: */*
Content-Length: 448

{
  "chat_color": "text",
  "chat_theme": "text",
  "chat_icon_file": "text",
  "chat_icon": "binary",
  "chat_button_file": "text",
  "chat_button": "binary",
  "welcome_message": "text",
  "model_description": "text",
  "language_toggle": false,
  "first_bot_message": "text",
  "conversation_header": "text",
  "widget_position": "text",
  "chat_height": 1,
  "chat_width": 1,
  "button_text": "text",
  "button_color": "text",
  "text_color": "text",
  "can_download_chat_messages": true,
  "primary_chat_color": "text"
}

No content