AI-Powered API Crash Course 2: Document Your AI Agent API with OpenAPI Specification

Welcome to Course 2 of the FabriXAI AI-Powered API Crash Course series. Now that you’ve built and tested your first AI agent in Course 1, it’s time to take the next step: documenting your API in a standardized, professional way using something called the OpenAPI Specification.

This might sound technical—but don’t worry. Whether you’re a solo creator, student, or first-time builder, we’ll walk you through it step by step.

In this course, you’ll learn how to:

✅ Prepare an OpenAPI spec using a template (easy and fast)

✅ Build your own OpenAPI spec from scratch (for full control)

✅ Validate and test your spec using Swagger Editor

Haven't built your AI Agent yet? Start with Crash Course 1: Create Your First AI Agent API.

‍

What Is an OpenAPI Specification (and Why Does It Matter)?

If you're new to APIs or don’t have a technical background, the term OpenAPI Specification might sound a little intimidating—but don’t worry, it’s actually pretty straightforward.

Think of it as a blueprint or instruction manual for your API. It clearly outlines:

• What your API does
• What kind of input it needs
• What kind of output it returns

This helps developers—and even other apps—understand exactly how to interact with your AI agent.

A well-structured OpenAPI Specification:

✅ Makes your API easier to understand and integrate

✅ Lets you test and validate your API before launch

✅ Is required to publish your agent on an API management platform like FabriXAPI (coming up in Course 3!)

It’s written in a format that both humans and machines can read (usually YAML or JSON) and works with tools like Swagger Editor, which lets you try out your API—even if you don’t write code.

‍

Getting Started

In this course, we’ll walk you through two simple ways to create an OpenAPI Specification for your FabriXAI agent:

1. Option 1: Use a Pre-Built OpenAPI Template (Recommended for Beginners)
2. Option 2: Build an OpenAPI Specification from Scratch

Choose the option that works best for you—either way, you’ll be one step closer to launching your own AI-powered API.

‍

Option 1: Use a Pre-Built OpenAPI Template (Recommended for Beginners)

The fastest way to get started is by using FabriXAI’s official OpenAPI (Swagger) templates—prebuilt for two agent types:

• WebApp (completion-based agents)
• Chatbot (message-based agents)

Not sure which one you’re using? Check the agent type in your FabriXAI builder or see What Are AI Agents?

‍

Step-by-Step: Create Your Spec from a Template

1. Download a template from the official GitHub repository, based on the the type of AI Agent you are working on:
   • WebApp Template
   • Chatbot Template
2. Open the file in a text editor or Swagger Editor.
3. Update the request body fields based on your agent’s configured inputs:
   • For WebApp, modify:
     • paths > /completion-messages > post > requestBody > ... > inputs > properties
   • For Chatbot, modify:
     • paths > /chat-messages > post > requestBody > ... > inputs > properties

‍

Example With Updated Inputs:

This time, we’ll continue with the AI agent Resource Allocation Planner. With the input fields like key_skills_expertise and project_name, part of your YAML might look like:

paths:
  /completion-messages:
    post:
      summary: Create Completion Message
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - response_mode
                - user
              properties:
                inputs:
                  type: object
                  description: Allows the entry of various variable values defined by the App. The inputs parameter contains multiple key/value pairs, with each key corresponding to a specific variable and each value being the specific value for that variable. The text generation application requires at least one key/value pair to be inputted.
                  properties:
                    key_skills_expertise:
                      type: string
                      description: Required skills
                    project_name:
                      type: string
                      description: Name of the project
                response_mode:
                  type: string
                  description: The mode of response return, supporting "streaming" or "blocking".
                  example: blocking
                user:
                  type: string
                  description: User identifier, used to define the identity of the end-user for retrieval and statistics. Should be uniquely defined by the developer within the application.
                  example: user

‍

Option 2: 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.

Step 1:  Define the Basic Structure

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

Note: You can find the server URL on the API tab of your AI agent’s configuration page.

openapi: 3.0.0
info:
  title: Resource Allocation Planner API
  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 'Bearer {API_KEY}' in the Authorization header"
security:
  - ApiKeyAuth: []

‍

Step 2: Add an Endpoint

Dfine your API’s capabilities by adding endpoints under the paths section. Each endpoint represents an action your agent can perform, such as 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 handle and respond to a request.

Here’s a sample section to copy and customize 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

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.

‍

Step 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.

‍

(Optional) Step 4: Add More Endpoints

If you’d like to expand your OpenAPI spec beyond the basic completion or chat endpoint, you can include additional supported endpoints based on what your agent can do. You can find the full list of examples in your agent’s “API” tab under Agent Builder > Integrations > API.

Some useful ones include:

• POST /files/upload - File Upload
• (Only applicable to WebApp) POST /completion-messages/{task_id}/stop – Stop a completion task
• (Only applicable to Chatbot) POST /chat-messages/{task_id}/stop – Stop a chat session
• GET /parameters – Get agent configuration
• POST /messages/{message_id}/feedbacks – Submit feedback
• GET /messages/{message_id}/suggested – Get suggested questions
• DELETE /conversations/{conversation_id} – Delete a conversation
• PUT /conversations/{conversation_id}/name –  Rename a conversation
• GET /meta – Retrieve conversation metadata
• POST /text-to-audio – Convert text to audio
• POST /audio-to-text – Transcribe audio to text

Note: These are the only supported endpoints for FabriXAI agents. You cannot create custom or unsupported endpoints—only use the ones officially provided in the FabriXAI API documentation.

‍

Step 5: Validate and Test Your Swagger File

Once your OpenAPI spec is ready:

1. Open the Swagger Editor.
2. Copy and paste your YAML file.
3. Fix any syntax or structure errors shown in the editor.
4. Click "Try it out" on any endpoint.
5. Enter your API Key in the Authorization field:
   • Format: Bearer {api_key}
   • Replace {api_key} with your actual API key
   • If you don’t have one, follow the Step 3 in Crash Course 1 to create an API key
6. Fill out the request body fields (e.g., inputs, response_mode, user)
7. Click "Execute" to send the request and view the response.

‍

What You’ve Accomplished

You now have a complete, ready-to-use OpenAPI Specification that:

✅ Clearly documents your AI agent’s capabilities

✅ Supports interactive testing via Swagger

✅ Is ready to be published on FabriXAPI in the next course

Want a refresher? You can revisit Crash Course 1: Create Your First AI Agent API →

‍

Next Up: Publish and Monetize Your API on FabriXAPI

In Course 3, you’ll learn how to publish your documented API on FabriXAPI—an online API store where users can test, subscribe to, and pay for access to your AI agent.

Ready to keep building? Continue to Crash Course 3: Launch and Monetize Your AI Agent API on FabriXAPI →

Or return to the Crash Course Introduction to view all lessons.

‍