openapi: 3.2.0
info:
  title: NeuralVerge AI Agents API
  version: 1.0.0
  description: NeuralVerge API for AI research workflows, search, extraction, and structured data source execution.
servers:
- url: https://api.neuralverge.ai
  description: NeuralVerge API
security:
- BearerAuth: []
tags:
- name: AI Agents
  description: Reusable saved agents executed through the API.
paths:
  /functions/v1/run-agent:
    post:
      tags:
      - AI Agents
      summary: Run Agent
      description: Runs a saved agent and returns a session id immediately.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agentId
              - instructions
              - settings
              properties:
                agentId:
                  type: string
                  format: uuid
                instructions:
                  type: string
                settings:
                  type: object
                  properties:
                    country_code:
                      type: string
                    search_enabled:
                      type: boolean
                    deepsearch_model:
                      type: string
                    finalizer_model:
                      type: string
            example:
              agentId: 00000000-0000-0000-0000-000000000001
              instructions: Analyze the company, identify key risks, and prepare a concise report.
              settings:
                country_code: us
                search_enabled: true
                deepsearch_model: base
                finalizer_model: gemini-3.0-pro
      responses:
        '200':
          description: Session started.
          content:
            application/json:
              example:
                session_id: 11111111-1111-1111-1111-111111111111
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Error
      operationId: postFunctionsV1RunAgent
      x-operation-id-source: derived
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key