Skip to main content

OpenApiPipeline

Description: Haystack pipeline for executing OpenAPI requests from a given OpenAPI spec.

Overview​

The OpenAPI Pipeline enables execution of API requests defined in a provided OpenAPI specification using natural language queries.
It interprets user intent, maps it to the most appropriate API operation from the OpenAPI dataset, executes the request, and returns the API response in a structured format.

This pipeline abstracts API complexity and allows users to interact with APIs using plain English while fully respecting the constraints and definitions of the OpenAPI spec.

Core Responsibilities​

  • Interpret natural language queries
  • Identify the correct API endpoint and HTTP method from the OpenAPI specification
  • Map query intent to path parameters, query parameters, headers, and request body
  • Execute the API call
  • Return the API response in a normalized format
  • Handle authentication and token lifecycle management

Processing Flow​

  1. User submits a natural language query
  2. OpenAPI spec dataset is analyzed
  3. Relevant API operation is selected
  4. Request payload is constructed (path, params, headers, body)
  5. Authentication is resolved (if required)
  6. API request is executed
  7. Response is returned to the caller

OpenAPI Spec Dataset​

The pipeline operates on an OpenAI / External APIs Dataset, which contains:

  • OpenAPI (Swagger) specification files
  • Endpoint definitions

This dataset acts as the source of truth for request selection and execution.

Authentication Support​

The OpenAPI Pipeline supports authenticated APIs defined in the OpenAPI specification.

Authentication Configuration​

If the OpenAPI spec requires authentication, users can configure:

  • Login URL
  • Client ID
  • Client Secret
  • Additional required credentials

Credential Placement​

For each authentication field, users can specify where the key-value pair should be passed:

  • Request Body
  • Query Parameters
  • Request Headers

This allows compatibility with diverse authentication implementations.

Authentication Flow​

  1. Detect authentication requirement from OpenAPI spec
  2. Execute authentication request using configured credentials
  3. Extract access token from response
  4. Attach token to subsequent API requests

Refresh Token Support​

The pipeline supports refresh token-based authentication for long-lived sessions.

Refresh Token Configuration​

When the Refresh Token toggle is enabled, users can configure:

  • Refresh Token URL
  • Refresh request payload fields
  • Token extraction rules

Refresh Token Storage​

  • On first successful login, the refresh token is stored in cache
  • Subsequent requests retrieve the refresh token from cache
  • Access tokens are refreshed automatically when expired

Refresh Token Flow​

  1. Initial authentication request is executed
  2. Refresh token is saved in cache
  3. When access token expires:
    • Refresh token is retrieved from cache
    • Refresh API is executed
    • New access token is obtained
  4. API request continues transparently

Parameter Injection Control​

For both authentication and refresh token requests, users can define:

  • Key name
  • Value
  • Injection location
    • Body
    • Query Parameters
    • Headers

This provides fine-grained control over request construction.

Key Features​

  • Natural language to API execution
  • OpenAPI-driven request selection
  • Automatic request payload construction
  • Authentication handling
  • Refresh token lifecycle management
  • Cached token reuse
  • Flexible parameter injection

Design Characteristics​

  • Spec-driven execution
  • Stateless request execution (token state via cache)
  • Secure credential handling
  • API-agnostic architecture
  • Deterministic request mapping

When to Use OpenAPI Pipeline​

Use the OpenAPI Pipeline when:

  • APIs are defined using OpenAPI specifications
  • Users want to interact with APIs using natural language
  • Authentication and token management must be handled automatically
  • Multiple endpoints must be selected dynamically based on intent
  • API execution needs to be standardized and scalable

Summary​

The OpenAPI Pipeline enables users to execute APIs defined in an OpenAPI specification using natural language queries. It converts user intent into the appropriate API request by selecting the correct endpoint, method, and parameters from the OpenAPI dataset, executes the call, and returns the response in a structured format. The pipeline includes built-in support for authenticated APIs, allowing users to configure login and refresh token flows with full control over how credentials are passed (headers, query params, or body). With automatic token caching, refresh handling, and spec-driven request mapping, the OpenAPI Pipeline simplifies secure, dynamic, and scalable API interactions without requiring users to understand underlying API details.