Version Management

The Assistant API provides comprehensive version control, allowing you to maintain multiple configurations of an assistant and deploy specific versions to production.

Create Version

Creates a new version of an existing assistant.

Endpoint

POST /api/ai-hub/assistant/:assistant_id/version

URL Parameters

  • assistant_id: The unique identifier of the assistant

Request Body

{
  "version_name": "v2.0.0",
  "name": "Customer Support Bot - Enhanced",
  "description": "Updated version with improved responses",
  "logo_url": "https://example.com/new-logo.png",
  "preferences": {
    "interface": {
      "header_background_color": "#059669",
      "header_text_color": "#FFFFFF",
      "chat_background_color": "#F0FDF4",
      "chat_border_color": "#86EFAC",
      "avatar_url": "https://example.com/avatar-v2.png",
      "chat_icon_url": "https://example.com/icon-v2.png",
      "agent_balloon_bg_color": "#D1FAE5",
      "agent_balloon_text_color": "#064E3B",
      "user_balloon_bg_color": "#059669",
      "user_balloon_text_color": "#FFFFFF"
    },
    "typography": {
      "subtitle_message": "I'm here to assist you",
      "greeting_message": "Welcome! How may I help you today?",
      "placeholder_input_message": "Ask me anything..."
    }
  },
  "integrations": {
    "whats_app": [
      {
        "phone_number": "+551198888888",
        "status": "validated"
      }
    ]
  },
  "knowledge_base": [
    {
      "folder_id": "550e8400-e29b-41d4-a716-446655440000",
      "usage_instructions": "Primary knowledge source"
    },
    {
      "folder_id": "550e8400-e29b-41d4-a716-446655440003",
      "usage_instructions": "FAQ and troubleshooting guides"
    }
  ]
}

Response

{
  "success": true,
  "message": "Version created successfully",
  "version": {
    "version_id": "660e8400-e29b-41d4-a716-446655440005",
    "version_name": "v2.0.0",
    "assistant_id": "550e8400-e29b-41d4-a716-446655440001",
    "created_at": "2024-01-20T14:30:00Z",
    "created_by": "user_123"
  }
}

Get Versions

Retrieves all versions for a specific assistant.

Endpoint

GET /api/ai-hub/assistant/:assistant_id/versions

URL Parameters

  • assistant_id: The unique identifier of the assistant

Example Request

GET /api/ai-hub/assistant/550e8400-e29b-41d4-a716-446655440001/versions

Response

{
  "success": true,
  "versions": [
    {
      "version_id": "660e8400-e29b-41d4-a716-446655440004",
      "version_name": "v1.0.0",
      "name": "Customer Support Bot",
      "created_at": "2024-01-15T10:30:00Z",
      "created_by": "user_123",
      "is_deployed": false
    },
    {
      "version_id": "660e8400-e29b-41d4-a716-446655440005",
      "version_name": "v2.0.0",
      "name": "Customer Support Bot - Enhanced",
      "created_at": "2024-01-20T14:30:00Z",
      "created_by": "user_123",
      "is_deployed": true,
      "deployed_at": "2024-01-20T15:00:00Z",
      "deployed_by": "user_123"
    }
  ],
  "total_versions": 2
}

Deploy Version

Deploys a specific version of an assistant, making it the active version.

Endpoint

POST /api/ai-hub/assistant/:assistant_id/version/:version_id/deploy

URL Parameters

  • assistant_id: The unique identifier of the assistant
  • version_id: The unique identifier of the version to deploy

Example Request

POST /api/ai-hub/assistant/550e8400-e29b-41d4-a716-446655440001/version/660e8400-e29b-41d4-a716-446655440005/deploy

Response

{
  "success": true,
  "message": "Version v2.0.0 deployed successfully",
  "deployment": {
    "version_id": "660e8400-e29b-41d4-a716-446655440005",
    "version_name": "v2.0.0",
    "deployed_at": "2024-01-20T15:00:00Z",
    "deployed_by": "user_123",
    "previous_version_id": "660e8400-e29b-41d4-a716-446655440004"
  }
}

Deployment Notes

  • Only one version can be deployed at a time
  • Deploying a new version automatically undeploys the previous version
  • The deployment history is maintained for audit purposes
  • Deployed versions cannot be deleted

Get Deployed Version

Retrieves the currently deployed version for an assistant.

Endpoint

GET /api/ai-hub/assistant/:assistant_id/deployed-version

URL Parameters

  • assistant_id: The unique identifier of the assistant

Example Request

GET /api/ai-hub/assistant/550e8400-e29b-41d4-a716-446655440001/deployed-version

Response

{
  "success": true,
  "deployed_version": {
    "version_id": "660e8400-e29b-41d4-a716-446655440005",
    "version_name": "v2.0.0",
    "name": "Customer Support Bot - Enhanced",
    "description": "Updated version with improved responses",
    "deployed_at": "2024-01-20T15:00:00Z",
    "deployed_by": "user_123",
    "preferences": {
      "interface": {
        "header_background_color": "#059669"
      },
      "typography": {
        "greeting_message": "Welcome! How may I help you today?"
      }
    },
    "integrations": {
      "whats_app": [
        {
          "phone_number": "+551198888888",
          "status": "validated"
        }
      ]
    },
    "knowledge_base": [
      {
        "folder_id": "550e8400-e29b-41d4-a716-446655440000",
        "usage_instructions": "Primary knowledge source"
      }
    ]
  }
}

Delete Version

Soft deletes a specific version of an assistant.

Endpoint

DELETE /api/ai-hub/assistant/:assistant_id/version/:version_id

URL Parameters

  • assistant_id: The unique identifier of the assistant
  • version_id: The unique identifier of the version to delete

Example Request

DELETE /api/ai-hub/assistant/550e8400-e29b-41d4-a716-446655440001/version/660e8400-e29b-41d4-a716-446655440004

Response

{
  "success": true,
  "message": "Version v1.0.0 deleted successfully",
  "deleted_version": {
    "version_id": "660e8400-e29b-41d4-a716-446655440004",
    "version_name": "v1.0.0",
    "deleted_at": "2024-01-21T10:00:00Z",
    "deleted_by": "user_123"
  }
}

Deletion Restrictions

  • Cannot delete a currently deployed version
  • Deleted versions are soft-deleted and can be restored if needed
  • All associated data (preferences, integrations, knowledge base) is preserved in the soft-delete
Table of Contents