Fincept Terminal Research API

openapi: 3.2.0
info:
  title: Fincept In Research API
  version: 3.0.0
  description: 'Operations tagged research across 2 of this provider''s published API definitions: fincept-in-openapi.json, fincept-in-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Research
paths:
  /research/papers/search:
    get:
      tags:
      - Research
      summary: Search Papers
      description: 'Search academic papers from arXiv with pagination

        Cost: 1 credit per 10 papers (per page)

        Rate limit: 1 request per second


        Returns 10 papers per page. Each page costs 1 credit.

        Example: page=1 returns papers 1-10, page=2 returns papers 11-20'
      operationId: search_papers_research_papers_search_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
          description: Search query (keywords separated by space)
          title: Query
        description: Search query (keywords separated by space)
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-indexed)
          default: 1
          title: Page
        description: Page number (1-indexed)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /research/papers/trending:
    get:
      tags:
      - Research
      summary: Get Trending Papers
      description: 'Get trending recent papers by topic with pagination

        Cost: 1 credit per 10 papers (per page)

        Rate limit: 1 request per second'
      operationId: get_trending_papers_research_papers_trending_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: topic
        in: query
        required: true
        schema:
          type: string
          description: Research topic
          title: Topic
        description: Research topic
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 7
          description: Days to look back
          default: 30
          title: Days
        description: Days to look back
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number
          default: 1
          title: Page
        description: Page number
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /research/content-reader:
    post:
      tags:
      - Research
      summary: Content Reader
      description: 'Extract and read content from web documents

        Cost: 0.25 credits per request

        Rate limit: 1 request per second'
      operationId: content_reader_research_content_reader_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentReaderRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/web-search:
    post:
      tags:
      - Research
      summary: Web Search
      description: Search the web for financial and market intelligence
      operationId: web_search_research_web_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/chat:
    post:
      tags:
      - Research
      summary: Fincept Chat
      description: Official Fincept AI Chat
      operationId: fincept_chat_research_chat_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/grokipedia:
    post:
      tags:
      - Research
      summary: Grokipedia Fetch
      description: 'Fetch knowledge articles from Grokipedia (xAI''s knowledge base)


        This endpoint retrieves comprehensive articles from Grokipedia, covering various topics

        with detailed content, references, and citations.


        Cost: 0.25 credits per request

        Rate limit: 1 request per second


        Parameters:

        - slug: Article slug/identifier (e.g., "artificial-intelligence", "climate-change")

        - extract_refs: Extract and include references (default: true)

        - truncate: Limit content to N characters (optional)

        - citations: Include citation formatting (default: false)


        Example slugs:

        - "bitcoin"

        - "machine-learning"

        - "quantum-computing"

        - "financial-markets"'
      operationId: grokipedia_fetch_research_grokipedia_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrokipediaRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/pdf/extract:
    post:
      tags:
      - Research
      summary: Extract Pdf Text
      description: 'Extract text from uploaded PDF file

        Dynamic Pricing:

        - 1-10 pages: 1 credit

        - 11-50 pages: 2 credits

        - 51-100 pages: 3 credits

        - 101-200 pages: 5 credits

        - 201+ pages: 10 credits

        Rate limit: 1 request per second

        Max file size: 10MB'
      operationId: extract_pdf_text_research_pdf_extract_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_extract_pdf_text_research_pdf_extract_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/health:
    get:
      tags:
      - Research
      summary: Research Health
      description: Health check for Fincept research module
      operationId: research_health_research_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /research/llm:
    post:
      tags:
      - Research
      summary: General Llm Inference
      description: 'General-purpose LLM endpoint for running agents, processing data, and AI tasks.


        This endpoint allows you to use Fincept API as your LLM provider for:

        - Running AI agents

        - Data processing and analysis

        - Code generation

        - Text summarization

        - Question answering

        - Any other LLM-based tasks


        Cost: 5 credits per successful response

        Note: Credits are ONLY deducted on successful LLM response. If the LLM fails, no credits are charged.


        Rate limit: 1 request per second'
      operationId: general_llm_inference_research_llm_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/llm/async:
    post:
      tags:
      - Research
      summary: Submit Llm Task Async
      description: 'Submit an LLM request for async processing.

        Returns a task_id immediately. Poll /research/llm/status/{task_id} for results.


        This is a drop-in addition to the existing synchronous POST /research/llm endpoint.

        The synchronous endpoint stays COMPLETELY UNCHANGED.


        Cost: 5 credits per successful response (same as sync endpoint)

        Note: Credits are ONLY deducted on successful LLM response. If the LLM fails, no credits are charged.


        Usage from client:

        1. POST /research/llm/async { prompt, temperature, max_tokens }

        -> { success: true, task_id: "abc123" }

        2. Poll GET /research/llm/status/abc123 every 3-5 seconds

        -> { status: "processing" } (keep polling)

        -> { status: "completed", data: { response: "...", ... } } (done)

        -> { status: "failed", error: "..." } (error)


        Tasks auto-expire after 30 minutes.'
      operationId: submit_llm_task_async_research_llm_async_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AsyncLLMRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncLLMResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/llm/status/{task_id}:
    get:
      tags:
      - Research
      summary: Get Llm Task Status
      description: 'Poll for async LLM task status.


        Returns:

        - status: "processing" -> keep polling (every 3-5 seconds)

        - status: "completed" -> data contains the LLM response (same format as sync endpoint)

        - status: "failed" -> error contains the failure reason


        Tasks auto-expire after 30 minutes.'
      operationId: get_llm_task_status_research_llm_status__task_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /research/visual-analysis:
    post:
      tags:
      - Research
      summary: Satellite Visual Analysis
      description: 'Multimodal Visual Analysis using MiniMax-M2.7 for satellite imagery and visual understanding.


        This endpoint enables advanced visual analysis capabilities including:

        - Satellite image analysis and interpretation

        - Geographic feature detection and classification

        - Land use and land cover analysis

        - Urban planning and infrastructure mapping

        - Environmental monitoring

        - Agricultural assessment

        - Disaster response and damage assessment

        - Object detection and counting in images

        - Visual question answering

        - Image description and captioning


        Model: MiniMax-M2.7 (Multimodal Vision-Language Model)

        - Native multimodal understanding

        - 128K context window

        - Advanced visual reasoning

        - Function calling capabilities

        - High-resolution image processing


        Cost: 10 credits per successful response

        Note: Credits are ONLY deducted on successful analysis. If the model fails, no credits are charged.


        Rate limit: 1 request per second


        Example Use Cases:

        - "Identify all buildings in this satellite image"

        - "What type of land use is shown in this area?"

        - "Detect any changes or anomalies in this image"

        - "Count the number of vehicles in this parking lot"

        - "Analyze the vegetation health in this agricultural field"'
      operationId: satellite_visual_analysis_research_visual_analysis_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisualAnalysisRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /research/news-events:
    get:
      tags:
      - Research
      summary: Get News Events
      description: 'Live geopolitics & conflict news events — updated every 30 minutes from 22 RSS feeds.


        **Cost:** 3 credits per request


        **Categories:** armed_conflict, explosions, civilian_violence, protests, riots,

        terrorism, political_violence, crisis, strategic, diplomacy, sanctions, elections,

        nuclear, cyber, maritime


        **Filters (all optional, combinable):**

        - country, city, cities (comma-separated)

        - event_category, source, date_from, date_to


        **Unique list modes (mutually exclusive):**

        - get_unique_cities, get_unique_countries, get_unique_categories, get_unique_sources


        **Pagination:** page + limit (default 30, max 100)'
      operationId: get_news_events_research_news_events_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: country
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by country (e.g., 'Iran', 'Ukraine')
          title: Country
        description: Filter by country (e.g., 'Iran', 'Ukraine')
      - name: city
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by single city (e.g., 'Baghdad')
          title: City
        description: Filter by single city (e.g., 'Baghdad')
      - name: cities
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated cities (e.g., 'Baghdad,Tehran,Kyiv')
          title: Cities
        description: Comma-separated cities (e.g., 'Baghdad,Tehran,Kyiv')
      - name: event_category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by category: armed_conflict, explosions, civilian_violence, protests, riots, terrorism, political_violence, crisis, strategic, diplomacy, sanctions, elections, nuclear, cyber, maritime'
          title: Event Category
        description: 'Filter by category: armed_conflict, explosions, civilian_violence, protests, riots, terrorism, political_violence, crisis, strategic, diplomacy, sanctions, elections, nuclear, cyber, maritime'
      - name: source
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by RSS source name (e.g., 'BBC World', 'Al Jazeera')
          title: Source
        description: Filter by RSS source name (e.g., 'BBC World', 'Al Jazeera')
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Start date filter ISO format (e.g., '2026-04-01')
          title: Date From
        description: Start date filter ISO format (e.g., '2026-04-01')
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: End date filter ISO format (e.g., '2026-04-20')
          title: Date To
        description: End date filter ISO format (e.g., '2026-04-20')
      - name: get_unique_cities
        in: query
        required: false
        schema:
          type: boolean
          description: Return list of unique cities instead of events
          default: false
          title: Get Unique Cities
        description: Return list of unique cities instead of events
      - name: get_unique_countries
        in: query
        required: false
        schema:
          type: boolean
          description: Return list of unique countries instead of events
          default: false
          title: Get Unique Countries
        description: Return list of unique countries instead of events
      - name: get_unique_categories
        in: query
        required: false
        schema:
          type: boolean
          description: Return list of unique event categories instead of events
          default: false
          title: Get Unique Categories
        description: Return list of unique event categories instead of events
      - name: get_unique_sources
        in: query
        required: false
        schema:
          type: boolean
          description: Return list of unique RSS sources instead of events
          default: false
          title: Get Unique Sources
        description: Return list of unique RSS sources instead of events
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (starts from 1)
          default: 1
          title: Page
        description: Page number (starts from 1)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Events per page (max 100)
          default: 30
          title: Limit
        description: Events per page (max 100)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /research/templates:
    get:
      tags:
      - Research
      summary: Get User Templates
      description: Get all templates accessible based on the caller's plan
      operationId: get_user_templates_research_templates_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /research/templates/download:
    get:
      tags:
      - Research
      summary: Download Template
      description: Download a specific template
      operationId: download_template_research_templates_download_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: tier
        in: query
        required: true
        schema:
          type: string
          title: Tier
      - name: filename
        in: query
        required: true
        schema:
          type: string
          title: Filename
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    LLMRequest:
      properties:
        prompt:
          type: string
          title: Prompt
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        max_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens
          default: 4096
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          default: 0.7
        tools:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Tools
        tool_choice:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tool Choice
      type: object
      required:
      - prompt
      title: LLMRequest
    VisualAnalysisRequest:
      properties:
        image_url:
          type: string
          title: Image Url
        prompt:
          type: string
          title: Prompt
        max_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens
          default: 4096
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          default: 0.7
        enable_thinking:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Thinking
          default: false
      type: object
      required:
      - image_url
      - prompt
      title: VisualAnalysisRequest
    TaskStatusResponse:
      properties:
        success:
          type: boolean
          title: Success
        task_id:
          type: string
          title: Task Id
        status:
          type: string
          title: Status
        data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Data
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      type: object
      required:
      - success
      - task_id
      - status
      title: TaskStatusResponse
    ContentReaderRequest:
      properties:
        url:
          type: string
          maxLength: 2083
          minLength: 1
          format: uri
          title: Url
        format:
          type: string
          title: Format
          default: markdown
      type: object
      required:
      - url
      title: ContentReaderRequest
    ChatRequest:
      properties:
        messages:
          items: {}
          type: array
          title: Messages
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
      type: object
      required:
      - messages
      title: ChatRequest
    AsyncLLMResponse:
      properties:
        success:
          type: boolean
          title: Success
        task_id:
          type: string
          title: Task Id
        message:
          type: string
          title: Message
          default: Task submitted
      type: object
      required:
      - success
      - task_id
      title: AsyncLLMResponse
    Body_extract_pdf_text_research_pdf_extract_post:
      properties:
        file:
          type: string
          format: binary
          title: File
          description: PDF file to process
      type: object
      required:
      - file
      title: Body_extract_pdf_text_research_pdf_extract_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WebSearchRequest:
      properties:
        query:
          type: string
          title: Query
        engine:
          type: string
          title: Engine
          default: google
      type: object
      required:
      - query
      title: WebSearchRequest
    GrokipediaRequest:
      properties:
        slug:
          type: string
          title: Slug
        extract_refs:
          type: boolean
          title: Extract Refs
          default: true
        truncate:
          anyOf:
          - type: integer
          - type: 'null'
          title: Truncate
        citations:
          type: boolean
          title: Citations
          default: false
      type: object
      required:
      - slug
      title: GrokipediaRequest
    AsyncLLMRequest:
      properties:
        prompt:
          type: string
          title: Prompt
        max_tokens:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Tokens
          default: 4096
        temperature:
          anyOf:
          - type: number
          - type: 'null'
          title: Temperature
          default: 0.7
        tools:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Tools
        tool_choice:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tool Choice
      type: object
      required:
      - prompt
      title: AsyncLLMRequest
      description: Request model for async LLM processing - same fields as LLMRequest
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
x-refined-from:
- fincept-in-openapi.json
- fincept-in-openapi.json
x-provenance:
  method: harvested
  publisher: Fincept Terminal
  source: https://api.fincept.in/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)