FabriXAI User Guide

# How to Prepare OpenAPI Specification for Your FabriXAI Agent

OpenAPI specification, also known as Swagger file, is a widely used format for documenting and testing APIs using YAML or JSON. This guide will help you prepare an OpenAPI specification (Swagger file) that describes how your FabriXAI agent's API works, using either a ready-made template or build from scratch:

# Prepare an OpenAPI Specification from Template

FabriXAI supports two types of agents: WebApp and Chatbot. To learn more about the differences, please refer to What Are AI Agents?.

  1. Download a Swagger template for your agent type:

  2. Open the downloaded Swagger template in a text editor or the Swagger Editor (opens new window).

  3. Update the input fields based on your agent’s configured inputs:

    • For WebApp agents, please locate the following section and update accordingly:
      path > /completion-messages > post > requestBody > content > application/json > schema > properties > inputs > properties
    • For Chatbot agents, please locate the following section and update accordingly:
      path > /chat-messages > post > requestBody > content > application/json > schema > properties > inputs > properties

  4. Example: If your agent uses the fields key_skills_expertise and project_name under User Inputs, you would update the Swagger file like this:

        inputs:
        type: object
        description: Contains key/value pairs for text input.
        properties:
            key_skills_expertise:
                type: string
                description: The key skill or expertise that needed for the project to be processed.
            project_name:
                type: string
                description: The name of project to be processed.

# Build an OpenAPI Specification from Scratch

If you prefer more flexibility or need to support custom behavior, you can also build your Swagger file from scratch instead of starting from a template. This is useful for advanced customization or when working with unique agent configurations.

  1. Define the Basic Structure

    Create a new YAML file (e.g. swagger.yaml) and add this basic structure:

    openapi: 3.0.0
info:
    title: API Documentation
    version: 1.0.0
servers:
    - url: https://console.fabrixai.com/v1
        description: FabriXAI API Server
components:
    securitySchemes:
        ApiKeyAuth:
        type: apiKey
        in: header
        name: Authorization
        description: "Use the API Key in the 'Authorization' header as 'Bearer {API_KEY}'"

security:
    - ApiKeyAuth: []

  2. Define API Endpoints (Paths)

    Now you’ll describe what your API can do by adding endpoints under the paths section. Each endpoint represents an action your agent can perform, like generating a message or uploading a file.

    Let’s start with a common example: generating a completion message (used by WebApp agents). This tells the system how to process and respond to a request.

    Here’s a sample section you can copy and modify in your Swagger file:

    paths:
    /completion-messages:
        post:
        summary: Create Completion Message
        description: Send a request to generate a message.
        security:
            - ApiKeyAuth: []  # This ensures this endpoint requires authentication
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            inputs:
                                type: object
                                description: Contains key/value pairs for text input.
                                properties:
                                    query:
                                    type: string
                                    description: The input text to be processed.
                            response_mode:
                                type: string
                                description: Response mode (streaming or blocking).
                                example: blocking
                            user:
                                type: string
                                description: User identifier for tracking.
                                example: user
        responses:
            '200':
            description: Success
            content:
                application/json:
                schema:
                    type: object
                    properties:
                        message_id:
                            type: string
                            description: Unique message ID
                        conversation_id:
                            type: string
                            description: Conversation ID
                        answer:
                            type: string
                            description: Generated response text
            '400':
                description: 'invalid_param: abnormal parameter input; app_unavailable: App configuration unavailable; provider_not_initialize: no available model credential configuration; provider_quota_exceeded: model invocation quota insufficient; model_currently_not_support: current model unavailable; completion_request_error: text generation failed;'
            '404':
                description: Conversation does not exist
            '500':
                description: Internal server error

    TIP

    WebApp vs Chatbot agents Configuration:

    • Use /completion-messages for WebApp agents.
    • Use /chat-messages for Chatbot agents.

    Remember: You’ll need to replace the example input fields (query, etc.) with the actual inputs your agent uses. See the next section for how to do this.

  3. Add Custom Inputs

    Just like in the template method, update the inputs section based on your agent’s configured fields.

        inputs:
        type: object
        description: Contains key/value pairs for text input.
        properties:
            key_skills_expertise:
                type: string
                description: The key skill or expertise that needed for the project to be processed.
            project_name:
                type: string
                description: The name of project to be processed.

  4. Add Additional Endpoints (Optional)

    You can document more endpoints as needed. You may refer to Agent Builder > Integrations > API page of your AI agent for the full list of examples.

    Some useful ones include:

    • POST /files/upload - File Upload
    • POST /completion-messages/{task_id}/stop – Stop Completion
    • POST /chat-messages/{task_id}/stop – Stop Chat
    • GET /parameters – Get Agent Parameters
    • POST /messages/{message_id}/feedbacks – Message Feedback
    • GET /messages/{message_id}/suggested – Suggested Questions
    • DELETE /conversations/{conversation_id} – Delete Conversation
    • PUT /conversations/{conversation_id}/name – Rename Conversation
    • GET /meta – Get Conversation Metadata
    • POST /text-to-audio – Text to Audio
    • POST /audio-to-text – Speech to Text

  5. Validate Your Swagger File

    1. Open the Swagger Editor (opens new window).
    2. Copy and paste your YAML file.
    3. Fix any syntax or structure errors shown in the editor.

  6. Test Your API Using Swagger UI

    1. Go to Swagger Editor (opens new window).
    2. Click "Try it out" on any endpoint.
    3. Enter your API Key in the Authorization field:
    4. Fill out the request body fields (e.g., inputs, response_mode, user)
    5. Click "Execute" to send the request and view the response.

← What is an AI Agent? →