openapi: 3.0.3
info:
  title: VectorForgeAI API
  description: |
    VectorForgeAI provides a powerful REST API for document management, vector search, and AI-powered conversations.

    ## Base URL
    All API requests should be sent to: `https://api.vectorforgeai.com/v1`

    ## Rate Limiting
    - **300 requests per minute** per client
    - Exceeding this limit will result in a `429 Too Many Requests` response

    ## Authentication
    All endpoints require:
    - Bearer token authentication via `Authorization` header
    - Team token via `Team-Token` header
  version: 1.0.0
  contact:
    email: support@vectorforgeai.com
servers:
  - url: https://api.vectorforgeai.com/v1
    description: Production API

security:
  - bearerAuth: []
    teamToken: []

tags:
  - name: Collections
    description: Document collection management
  - name: Documents
    description: Document operations within collections
  - name: Search
    description: Vector search operations
  - name: Conversations
    description: Conversational AI and chat operations
  - name: Completions
    description: LLM text completions
  - name: Feedback
    description: Conversation feedback and ratings

paths:
  /collections:
    get:
      tags:
        - Collections
      summary: List all collections
      description: Retrieve all collections that belong to your account
      operationId: listCollections
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'

    post:
      tags:
        - Collections
      summary: Create a collection
      description: Create a new document collection to organize your data
      operationId: createCollection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Name of the collection
                  example: "Research Papers"
                description:
                  type: string
                  maxLength: 255
                  description: Description of the collection
                  example: "Collection of AI research papers"
                chunk_overlap:
                  type: number
                  format: float
                  minimum: 0
                  maximum: 100
                  default: 17.0
                  description: Percentage of text overlap between chunks (0-100)
                  example: 15.0
      responses:
        '201':
          description: Collection created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  collection:
                    $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /collections/{collection}:
    delete:
      tags:
        - Collections
      summary: Delete a collection
      description: Permanently delete a collection and all its associated documents and embeddings. This action cannot be undone.
      operationId: deleteCollection
      parameters:
        - name: collection
          in: path
          required: true
          description: ID of the collection to delete
          schema:
            type: string
            example: "abc123xyz456"
      responses:
        '200':
          description: Collection deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Collection deleted successfully."
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /collections/{collection}/documents:
    get:
      tags:
        - Documents
      summary: List documents in a collection
      description: Retrieve all documents within a specific collection with pagination support
      operationId: listDocuments
      parameters:
        - name: collection
          in: path
          required: true
          description: ID of the collection to list documents from
          schema:
            type: string
            example: "abc123xyz456"
        - name: limit
          in: query
          required: false
          description: Number of documents to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: page
          in: query
          required: false
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Document'
                      first_page_url:
                        type: string
                        example: "https://api.vectorforgeai.com/v1/collections/abc123xyz456/documents?page=1"
                      from:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 3
                      per_page:
                        type: integer
                        example: 20
                      to:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 42
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

    post:
      tags:
        - Documents
      summary: Add a document to a collection
      description: Add a new document to an existing collection. If a document with the same identifier already exists, it will be updated.
      operationId: createDocument
      parameters:
        - name: collection
          in: path
          required: true
          description: ID of the collection to add the document to
          schema:
            type: string
            example: "abc123xyz456"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - identifier
                - body
              properties:
                identifier:
                  type: string
                  maxLength: 512
                  description: Unique identifier for the document
                  example: "doc-001"
                title:
                  type: string
                  maxLength: 512
                  description: Title of the document
                  example: "What is VectorForgeAI"
                body:
                  type: string
                  description: The main content of the document
                  example: "VectorForgeAI is a platform that simplifies AI infrastructure..."
                metadata:
                  type: object
                  description: Key-value pairs with additional data about the document
                  additionalProperties: true
                  example:
                    author: "Jane Smith"
                    category: "Documentation"
                system_context:
                  type: string
                  maxLength: 512
                  description: Extra information or instructions for problem-solution generation
                  example: "Focus on technical details"
      responses:
        '201':
          description: Document created or updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  state:
                    type: string
                    enum: [created, updated]
                    example: "created"
                  document:
                    $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /collections/{collection}/documents/search:
    get:
      tags:
        - Search
      summary: Search documents in a collection
      description: Perform a semantic search across documents in a collection using natural language queries
      operationId: searchDocuments
      parameters:
        - name: collection
          in: path
          required: true
          description: ID of the collection to search
          schema:
            type: string
            example: "abc123xyz456"
        - name: query
          in: query
          required: true
          description: The search query in natural language
          schema:
            type: string
            maxLength: 512
            example: "How does AI embedding work"
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/Document'
                        - type: object
                          properties:
                            score:
                              type: number
                              format: float
                              minimum: 0
                              maximum: 1
                              description: Cosine similarity score (0-1, higher is more similar)
                              example: 0.892
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /collections/{collection}/documents/{identifier}:
    delete:
      tags:
        - Documents
      summary: Delete a document
      description: Permanently remove a document from a collection, including all its vector embeddings. This action cannot be undone.
      operationId: deleteDocument
      parameters:
        - name: collection
          in: path
          required: true
          description: ID of the collection containing the document
          schema:
            type: string
            example: "abc123xyz456"
        - name: identifier
          in: path
          required: true
          description: Unique identifier of the document to delete
          schema:
            type: string
            example: "doc-001"
      responses:
        '200':
          description: Document deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Document deleted successfully."
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /messages:
    post:
      tags:
        - Conversations
      summary: Create or continue a conversation
      description: Send a message to create a new conversation or continue an existing one with optional document context and tool support
      operationId: sendMessage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user
              properties:
                user:
                  type: string
                  description: A unique identifier for the end user
                  example: "user_12345"
                message:
                  type: string
                  description: The user's message (required unless tool_results is provided)
                  example: "What are the key features of VectorForgeAI?"
                conversation:
                  type: string
                  description: Conversation ID from a previous response (omit to create a new conversation)
                  example: "jkl789mno012"
                system_context:
                  type: string
                  description: System instructions for the AI
                  example: "You are a helpful AI assistant for VectorForgeAI."
                user_context:
                  type: string
                  description: User-specific context to guide the conversation
                  example: "The user is a developer familiar with APIs"
                collections:
                  type: array
                  items:
                    type: string
                  description: Array of collection IDs to use for knowledge retrieval
                  example: ["abc123xyz456", "def456uvw789"]
                role:
                  type: string
                  enum: [user, assistant, system, tool]
                  default: user
                  description: Message role
                tools:
                  type: array
                  items:
                    $ref: '#/components/schemas/Tool'
                  description: Array of tools the AI can use (for function calling)
                tool_results:
                  type: array
                  items:
                    $ref: '#/components/schemas/ToolResult'
                  description: Results from tool execution (for function calling responses)
                no_tools:
                  type: boolean
                  default: false
                  description: If true, disables tool usage for this request
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ConversationResponse'
                  - $ref: '#/components/schemas/ToolCallResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /messages/{conversation}:
    get:
      tags:
        - Conversations
      summary: Retrieve conversation history
      description: Get the message history for a specific conversation
      operationId: getConversation
      parameters:
        - name: conversation
          in: path
          required: true
          description: ID of the conversation to retrieve
          schema:
            type: string
            example: "jkl789mno012"
      responses:
        '200':
          description: Conversation history retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

    delete:
      tags:
        - Conversations
      summary: Delete a conversation
      description: Permanently delete a conversation and all its associated messages
      operationId: deleteConversation
      parameters:
        - name: conversation
          in: path
          required: true
          description: ID of the conversation to delete
          schema:
            type: string
            example: "jkl789mno012"
      responses:
        '200':
          description: Conversation deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Conversation deleted successfully."
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /messages/{conversation}/rate:
    post:
      tags:
        - Feedback
      summary: Rate a conversation message
      description: Submit a rating (upvote/downvote) for a specific assistant message in a conversation
      operationId: rateMessage
      parameters:
        - name: conversation
          in: path
          required: true
          description: The nanoid of the conversation containing the message
          schema:
            type: string
            example: "abc123def456"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - user
                - message_id
                - rating
              properties:
                user:
                  type: string
                  description: The user identifier that the conversation belongs to
                  example: "user_12345"
                message_id:
                  type: string
                  description: The ID of the message to rate
                  example: "resp_assi_xyz789"
                rating:
                  type: integer
                  enum: [1, -1]
                  description: The rating value (1 for upvote, -1 for downvote)
                  example: 1
      responses:
        '200':
          description: Message rated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Message rated successfully."
                  rating:
                    type: integer
                    example: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

  /responses:
    post:
      tags:
        - Completions
      summary: Generate a completion
      description: Generate an AI text completion with optional context and configurable parameters
      operationId: generateCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  description: The user's message or query
                  example: "What is vector embedding and how does it work?"
                context:
                  type: string
                  description: Additional dynamic user context to guide the model's response
                  example: "You are a helpful AI assistant for VectorForgeAI."
                system_prompt:
                  type: string
                  description: System instructions for the model
                  example: "Provide accurate technical information"
                effort:
                  type: string
                  enum: [minimal, low, medium, high]
                  default: medium
                  description: |
                    Reasoning effort level:
                    - minimal: Fastest responses without reasoning. Doesn't support tools.
                    - low: Light reasoning for straightforward tasks.
                    - medium: Balanced reasoning for most use cases.
                    - high: Deep reasoning for complex problems.
                verbosity:
                  type: string
                  enum: [low, medium, high]
                  default: medium
                  description: |
                    Response verbosity level:
                    - low: Concise, direct answers.
                    - medium: Balanced detail and length.
                    - high: Detailed, comprehensive responses.
                max_tokens:
                  type: integer
                  minimum: 1
                  maximum: 32768
                  default: 1024
                  description: Maximum length of generated response
                model:
                  type: string
                  enum: [standard, pro]
                  default: standard
                  description: |
                    The model to use:
                    - standard: Efficient model for most use cases.
                    - pro: Advanced model with enhanced capabilities (uses 4x more tokens).
      responses:
        '200':
          description: Completion generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    description: The generated AI response
                    example: "Vector embedding is a technique that converts text, images, or other data into numerical vectors..."
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from your VectorForgeAI account
    teamToken:
      type: apiKey
      in: header
      name: Team-Token
      description: Team token for multi-tenant access

  schemas:
    Collection:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the collection
          example: "abc123xyz456"
        name:
          type: string
          description: Name of the collection
          example: "Research Papers"
        description:
          type: string
          description: Description of the collection
          example: "Collection of AI research papers"
        created_at:
          type: string
          format: date-time
          example: "2025-05-01T09:22:15.789Z"
        updated_at:
          type: string
          format: date-time
          example: "2025-05-01T09:22:15.789Z"
        chunk_overlap:
          type: number
          format: float
          description: Percentage of text overlap between chunks
          example: 10.0

    Document:
      type: object
      properties:
        identifier:
          type: string
          description: Unique identifier for the document
          example: "doc-001"
        title:
          type: string
          description: Title of the document
          example: "What is VectorForgeAI"
        body:
          type: string
          description: The main content of the document
          example: "VectorForgeAI is a platform that simplifies AI infrastructure..."
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata about the document
          example:
            author: "Jane Smith"
            department: "Marketing"
        structured_problems:
          type: array
          items:
            type: object
            properties:
              tags:
                type: array
                items:
                  type: string
              problem:
                type: string
              summary:
                type: string
              solution:
                type: string
          description: Auto-generated problem-solution pairs
        created_at:
          type: string
          format: date-time
          example: "2025-05-01T09:15:22.123Z"
        updated_at:
          type: string
          format: date-time
          example: "2025-05-01T09:15:22.123Z"

    Message:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the message
          example: "mess_user_abc123def456"
        role:
          type: string
          enum: [user, assistant, system, tool]
          description: Role of the message sender
          example: "user"
        content:
          type: string
          description: The message content
          example: "What are the key features of VectorForgeAI?"
        timestamp:
          type: string
          format: date-time
          example: "2025-05-10T08:42:15.123Z"

    ConversationResponse:
      type: object
      properties:
        id:
          type: string
          description: Response ID
          example: "resp_assi_xyz123abc456"
        type:
          type: string
          enum: [response]
          example: "response"
        conversation_id:
          type: string
          description: ID of the conversation
          example: "jkl789mno012"
        response:
          type: string
          description: The AI's response
          example: "VectorForgeAI offers several key features..."
        documents:
          type: array
          items:
            type: object
            properties:
              identifier:
                type: string
              title:
                type: string
              body_intro:
                type: string
              metadata:
                type: object
          description: Relevant documents used for context
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: Recent conversation history

    ToolCallResponse:
      type: object
      properties:
        type:
          type: string
          enum: [tool_calls]
          example: "tool_calls"
        conversation_id:
          type: string
          description: ID of the conversation
          example: "vwx345yz678"
        tool_calls:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique identifier for the tool call
                example: "call_123456789"
              name:
                type: string
                description: Name of the tool to call
                example: "get_weather"
              arguments:
                type: object
                additionalProperties: true
                description: Arguments to pass to the tool

    Tool:
      type: object
      properties:
        name:
          type: string
          description: Name of the tool
          example: "get_weather"
        description:
          type: string
          description: Description of what the tool does
          example: "Get current weather information for a location"
        parameters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: "location"
              type:
                type: string
                example: "string"
              description:
                type: string
                example: "The city and state or country"
              required:
                type: boolean
                example: true

    ToolResult:
      type: object
      properties:
        tool_id:
          type: string
          description: ID of the tool call
          example: "call_123456789"
        tool_name:
          type: string
          description: Name of the tool
          example: "get_weather"
        arguments:
          type: object
          additionalProperties: true
          description: Arguments that were passed to the tool
        result:
          type: object
          additionalProperties: true
          description: Result from the tool execution

    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation errors by field

  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Unauthenticated."

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Resource not found."

    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Too Many Requests"
              retry_after:
                type: integer
                description: Number of seconds to wait before retrying
                example: 60