Algenta Products API

openapi: 3.2.0
info:
  title: Algenta Ai Products API
  version: 1.0.0
  description: 'Operations tagged Products across 2 of this provider''s published API definitions: api.algenta.ai-openapi.json, gateway.algenta.ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.algenta.ai
- url: /
tags:
- name: Products
paths:
  /v1/decision:
    post:
      tags:
      - Products
      summary: Get an optimal decision
      description: 'Give Algenta your inputs and constraints. Get back the optimal action with confidence, risk, and plain-English reasoning.


        Evaluates thousands of possible scenarios in milliseconds using the Algenta API — no statistics or simulation expertise required.'
      operationId: decision_v1_decision_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DecisionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecisionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - LegacyApiKey: []
    servers:
    - url: https://api.algenta.ai
  /v1/agent/run:
    post:
      tags:
      - Products
      summary: Run an AI agent task
      description: 'Give the Algenta Agent Engine a task. It breaks it down, uses tools (search, simulate, optimize, calculate), and returns a structured result.


        Direct replacement for LangChain and LangGraph agent pipelines.'
      operationId: agent_run_v1_agent_run_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRunRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - LegacyApiKey: []
    servers:
    - url: https://api.algenta.ai
  /v1/optimize:
    post:
      tags:
      - Products
      summary: Optimize a business variable
      description: 'Find the optimal value for pricing, routing, scheduling, or resource allocation.


        Describe your objective and constraints in plain English — Algenta finds the best configuration across thousands of iterations.'
      operationId: optimize_v1_optimize_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OptimizeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptimizeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - LegacyApiKey: []
    servers:
    - url: https://api.algenta.ai
  /v1/retrieve:
    post:
      tags:
      - Products
      summary: Search a knowledge base
      description: 'Search documents or a connected data source and get ranked, relevant results.


        Combines BM25 keyword search, dense vector similarity, and cross-encoder reranking. No setup required — pass documents inline or connect a data source.'
      operationId: retrieve_v1_retrieve_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - LegacyApiKey: []
    servers:
    - url: https://api.algenta.ai
  /v1/forecast:
    post:
      tags:
      - Products
      summary: Forecast a business metric
      description: 'Forecast any metric — revenue, demand, capacity — using historical data.


        Combines time-series analysis with Monte Carlo uncertainty quantification. Returns point forecasts with confidence intervals for each period.'
      operationId: forecast_v1_forecast_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForecastRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForecastResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - LegacyApiKey: []
    servers:
    - url: https://api.algenta.ai
components:
  schemas:
    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
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AgentRunRequest:
      properties:
        task:
          type: string
          minLength: 5
          title: Task
          description: What should the agent do?
        context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Context
          description: Additional context or data
        tools:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tools
          description: 'Tools to make available: search, simulate, optimize, calculate, summarize'
        max_steps:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Max Steps
          description: Maximum execution steps
          default: 10
        output_format:
          type: string
          title: Output Format
          description: 'Output format: text, json, markdown'
          default: text
      type: object
      required:
      - task
      title: AgentRunRequest
      description: 'Give Algenta a task. It plans, executes tools, and returns a structured result.


        Drop-in replacement for LangChain / LangGraph agent workflows.'
    OptimizeVariable:
      properties:
        name:
          type: string
          title: Name
        min:
          type: number
          title: Min
        max:
          type: number
          title: Max
        step:
          anyOf:
          - type: number
          - type: 'null'
          title: Step
        unit:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit
      type: object
      required:
      - name
      - min
      - max
      title: OptimizeVariable
    DecisionInput:
      properties:
        name:
          type: string
          title: Name
          description: Variable name, e.g. 'revenue'
        value:
          type: number
          title: Value
          description: Expected / central value
        low:
          anyOf:
          - type: number
          - type: 'null'
          title: Low
          description: Pessimistic value (optional)
        high:
          anyOf:
          - type: number
          - type: 'null'
          title: High
          description: Optimistic value (optional)
        unit:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit
          description: Unit label, e.g. 'USD'
      type: object
      required:
      - name
      - value
      title: DecisionInput
      description: A named input value with optional uncertainty range.
    ForecastRequest:
      properties:
        metric:
          type: string
          title: Metric
          description: What you're forecasting, e.g. 'monthly_revenue'
        history:
          items:
            type: number
          type: array
          maxItems: 1000
          minItems: 3
          title: History
          description: Historical values (most recent last)
        horizon:
          type: integer
          maximum: 120.0
          minimum: 1.0
          title: Horizon
          description: How many periods ahead to forecast
          default: 12
        seasonality:
          type: boolean
          title: Seasonality
          description: Account for seasonal patterns
          default: true
        confidence_level:
          type: number
          maximum: 0.99
          minimum: 0.5
          title: Confidence Level
          description: Confidence interval width
          default: 0.9
      type: object
      required:
      - metric
      - history
      title: ForecastRequest
      description: 'Forecast what will happen based on historical data and business drivers.


        Use cases: demand forecasting, revenue projection, capacity planning.'
    OptimizeConstraint:
      properties:
        expression:
          type: string
          title: Expression
          description: e.g. 'margin > 0.2', 'cost < 50000'
        required:
          type: boolean
          title: Required
          default: true
      type: object
      required:
      - expression
      title: OptimizeConstraint
    RetrieveDocument:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        content:
          type: string
          title: Content
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
      type: object
      required:
      - content
      title: RetrieveDocument
    RetrieveResult:
      properties:
        rank:
          type: integer
          title: Rank
        document_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Document Id
        content:
          type: string
          title: Content
        relevance_score:
          type: number
          title: Relevance Score
        snippet:
          type: string
          title: Snippet
      type: object
      required:
      - rank
      - document_id
      - content
      - relevance_score
      - snippet
      title: RetrieveResult
    ForecastPeriod:
      properties:
        period:
          type: integer
          title: Period
        forecast:
          type: number
          title: Forecast
        lower_bound:
          type: number
          title: Lower Bound
        upper_bound:
          type: number
          title: Upper Bound
        trend:
          type: string
          title: Trend
      type: object
      required:
      - period
      - forecast
      - lower_bound
      - upper_bound
      - trend
      title: ForecastPeriod
    AgentRunResponse:
      properties:
        run_id:
          type: string
          title: Run Id
        status:
          type: string
          title: Status
        result:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          title: Result
        steps:
          items:
            $ref: '#/components/schemas/AgentStep'
          type: array
          title: Steps
        tools_used:
          items:
            type: string
          type: array
          title: Tools Used
        latency_ms:
          type: number
          title: Latency Ms
      type: object
      required:
      - run_id
      - status
      - result
      - steps
      - tools_used
      - latency_ms
      title: AgentRunResponse
    OptimizeRequest:
      properties:
        objective:
          type: string
          title: Objective
          description: What to optimize, e.g. 'maximize profit', 'minimize cost', 'maximize throughput'
        variables:
          items:
            $ref: '#/components/schemas/OptimizeVariable'
          type: array
          title: Variables
          description: Variables to optimize with their allowed ranges
        constraints:
          items:
            $ref: '#/components/schemas/OptimizeConstraint'
          type: array
          title: Constraints
          description: Business constraints that must be satisfied
        iterations:
          type: integer
          maximum: 100000.0
          minimum: 100.0
          title: Iterations
          description: Search iterations
          default: 1000
        engine:
          type: string
          title: Engine
          description: 'Simulation engine. ''auto'' selects the best engine automatically. Options: lhs (recommended for optimization), monte_carlo, qmc_sobol'
          default: auto
      type: object
      required:
      - objective
      - variables
      title: OptimizeRequest
      description: 'Find the best value given inputs, constraints, and an objective.


        Use cases: pricing, routing, scheduling, resource allocation.

        No math required — just describe what you''re optimizing.'
    AgentStep:
      properties:
        step:
          type: integer
          title: Step
        action:
          type: string
          title: Action
        tool:
          anyOf:
          - type: string
          - type: 'null'
          title: Tool
        result:
          anyOf:
          - type: string
          - type: 'null'
          title: Result
        status:
          type: string
          title: Status
          default: completed
      type: object
      required:
      - step
      - action
      title: AgentStep
    ForecastResponse:
      properties:
        forecast_id:
          type: string
          title: Forecast Id
        metric:
          type: string
          title: Metric
        baseline:
          type: number
          title: Baseline
          description: Most recent historical value
        forecast_mean:
          type: number
          title: Forecast Mean
          description: Expected value at end of horizon
        total_change_pct:
          type: number
          title: Total Change Pct
          description: Expected % change over horizon
        periods:
          items:
            $ref: '#/components/schemas/ForecastPeriod'
          type: array
          title: Periods
        scenarios_evaluated:
          type: integer
          title: Scenarios Evaluated
        latency_ms:
          type: number
          title: Latency Ms
      type: object
      required:
      - forecast_id
      - metric
      - baseline
      - forecast_mean
      - total_change_pct
      - periods
      - scenarios_evaluated
      - latency_ms
      title: ForecastResponse
    RetrieveRequest:
      properties:
        query:
          type: string
          minLength: 3
          title: Query
          description: What are you looking for?
        documents:
          anyOf:
          - items:
              $ref: '#/components/schemas/RetrieveDocument'
            type: array
          - type: 'null'
          title: Documents
          description: Documents to search (inline mode)
        collection_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Collection Id
          description: ID of a connected data source to search
        top_k:
          type: integer
          maximum: 50.0
          minimum: 1.0
          title: Top K
          description: Number of results to return
          default: 5
        rerank:
          type: boolean
          title: Rerank
          description: Apply cross-encoder reranking for higher accuracy
          default: true
      type: object
      required:
      - query
      title: RetrieveRequest
      description: 'Search your knowledge base and get ranked, relevant results.


        Plug-and-play enterprise search and RAG pipeline.

        Pass documents inline or reference a connected collection.'
    DecisionRequest:
      properties:
        inputs:
          items:
            $ref: '#/components/schemas/DecisionInput'
          type: array
          title: Inputs
          description: Business inputs with optional uncertainty ranges
          examples:
          - - high: 180000
              low: 80000
              name: revenue
              unit: USD
              value: 120000
            - high: 100000
              low: 50000
              name: cost
              unit: USD
              value: 70000
        objective:
          type: string
          title: Objective
          description: 'What to optimize: maximize_value, minimize_risk, maximize_profit, minimize_cost'
          default: maximize_value
        risk_tolerance:
          type: string
          title: Risk Tolerance
          description: 'How much risk is acceptable: low, medium, high'
          default: medium
        scenarios:
          type: integer
          maximum: 1000000.0
          minimum: 1000.0
          title: Scenarios
          description: How many scenarios to evaluate (more = higher confidence)
          default: 10000
        engine:
          type: string
          title: Engine
          description: 'Simulation engine. ''auto'' (default) selects the best engine automatically based on your data shape. Options: monte_carlo, lhs, qmc_sobol, bootstrap, mcmc, importance_sampling, time_series, sensitivity'
          default: auto
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
          description: Optional label for this decision
      type: object
      required:
      - inputs
      title: DecisionRequest
      description: 'Ask Algenta: given these inputs and constraints, what should I do?


        Algenta tests thousands of possible outcomes and returns the optimal action

        with confidence, risk, and reasoning — no statistics knowledge required.'
    DecisionResponse:
      properties:
        decision_id:
          type: string
          title: Decision Id
        action:
          type: string
          title: Action
          description: 'Recommended action: proceed, pause, reject, or custom'
        confidence:
          type: number
          title: Confidence
          description: Confidence in this recommendation (0–1)
        reasoning:
          type: string
          title: Reasoning
          description: Plain-English explanation
        why:
          items:
            type: string
          type: array
          title: Why
          description: 3 crisp reasons behind this recommendation
        expected_outcome:
          type: number
          title: Expected Outcome
          description: Expected value in your input units
        downside_risk:
          type: number
          title: Downside Risk
          description: Value at 5th percentile (worst-case)
        upside_potential:
          type: number
          title: Upside Potential
          description: Value at 95th percentile (best-case)
        probability_of_loss:
          type: number
          title: Probability Of Loss
          description: Probability of negative outcome
        scenarios_evaluated:
          type: integer
          title: Scenarios Evaluated
        latency_ms:
          type: number
          title: Latency Ms
      type: object
      required:
      - decision_id
      - action
      - confidence
      - reasoning
      - why
      - expected_outcome
      - downside_risk
      - upside_potential
      - probability_of_loss
      - scenarios_evaluated
      - latency_ms
      title: DecisionResponse
    RetrieveResponse:
      properties:
        retrieval_id:
          type: string
          title: Retrieval Id
        query:
          type: string
          title: Query
        results:
          items:
            $ref: '#/components/schemas/RetrieveResult'
          type: array
          title: Results
        total_searched:
          type: integer
          title: Total Searched
        latency_ms:
          type: number
          title: Latency Ms
      type: object
      required:
      - retrieval_id
      - query
      - results
      - total_searched
      - latency_ms
      title: RetrieveResponse
    OptimizeResponse:
      properties:
        optimization_id:
          type: string
          title: Optimization Id
        status:
          type: string
          title: Status
        optimal_values:
          additionalProperties:
            type: number
          type: object
          title: Optimal Values
        objective_value:
          type: number
          title: Objective Value
        improvement_vs_midpoint:
          type: number
          title: Improvement Vs Midpoint
          description: '% improvement vs naive midpoint solution'
        constraints_satisfied:
          type: boolean
          title: Constraints Satisfied
        iterations_run:
          type: integer
          title: Iterations Run
        latency_ms:
          type: number
          title: Latency Ms
      type: object
      required:
      - optimization_id
      - status
      - optimal_values
      - objective_value
      - improvement_vs_midpoint
      - constraints_satisfied
      - iterations_run
      - latency_ms
      title: OptimizeResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
      description: 'Canonical v1 authentication. Use Authorization: Bearer <api_key>.'
    LegacyApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Legacy compatibility header for existing v1 clients.
x-refined-from:
- api.algenta.ai-openapi.json


# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/algenta-ai/openapi/algenta-ai-products-api-openapi.yml