openapi: 3.2.0
info:
  title: NeuralVerge AI Research 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 Research
  description: Research workflows and session tracking.
paths:
  /functions/v1/run-research:
    post:
      tags:
      - AI Research
      summary: Run Research
      description: Starts the full research workflow and returns a session id immediately.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - instructions
              - settings
              properties:
                instructions:
                  type: string
                  description: Main research task.
                settings:
                  type: object
                  properties:
                    country_code:
                      type: string
                    search_enabled:
                      type: boolean
                    deepsearch_model:
                      type: string
                    finalizer_model:
                      type: string
                    extract_schema_json:
                      type: string
            example:
              instructions: Analyze the company and identify the main risks.
              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
        '402':
          description: Payment Required
        '500':
          description: Internal Error
      operationId: postFunctionsV1RunResearch
      x-operation-id-source: derived
  /functions/v1/get-session-status:
    get:
      tags:
      - AI Research
      summary: Get Session Status
      description: Returns the current status of a session and the final result when complete.
      parameters:
      - name: session_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
        description: Session identifier.
      responses:
        '200':
          description: Session status.
          content:
            application/json:
              example:
                session_id: 11111111-1111-1111-1111-111111111111
                status: complete
                results:
                  kind: deepsearch
                  human: '# Research summary


                    - Main takeaway: Example risk is moderate.'
                  machine:
                    summary: Example risk is moderate.
                    risk_level: medium
                  total_points: 50
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Error
      operationId: getFunctionsV1GetSessionStatus
      x-operation-id-source: derived
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key