Skip to main content

API Overview

The Infino REST API provides a single gateway to query your data with context.

API Terminology​

Infino uses universal terminology that works consistently across SQL databases, NoSQL stores, search engines, and data warehouses. This makes the API easier to understand regardless of your data background.

Core Concepts​

Infino TermWhat It MeansSQL EquivalentNoSQL/Search Equivalent
SourceA data system you connect toDatabase serverElasticsearch cluster, MongoDB instance
DatasetA collection of related recordsTableIndex (Elasticsearch), Collection (MongoDB)
RecordA single data entryRowDocument (NoSQL), Log entry
FieldAn individual data attributeColumnField (NoSQL), Property

Why This Matters​

Problem: Different systems use different terms:

  • A "table" in MySQL = "index" in Elasticsearch = "collection" in MongoDB
  • A "row" in PostgreSQL = "document" in OpenSearch = "record" in DynamoDB
  • A "column" in SQL = "field" in NoSQL = "property" in document stores

Solution: Infino uses Source/Dataset/Record/Field consistently across all systems, so:

  • You learn one API that works everywhere
  • Documentation is clear regardless of your background
  • AI agents can work across diverse systems with consistent terminology

Examples in Context​

Working with a SQL database:

  • Source: mysql://prod-database
  • Dataset: customers (a table)
  • Record: One customer row
  • Field: email (a column)

Working with Elasticsearch:

  • Source: elasticsearch://logs-cluster
  • Dataset: application-logs (an index)
  • Record: One log entry (a document)
  • Field: message (a field)

Working with Fino datasets:

  • Dataset: sales-staging (for correlation)
  • Record: One sales transaction
  • Field: amount (a field)

Universal Access Layer​

Infino's API enables:

  • Query data where it lives - Access your data sources without ETL
  • Unified interface - Same API for all connected sources
  • Agent and human access - Programmatic and interactive workflows

Supported Query Interfaces​

Execute queries using multiple formats:

  • Query DSL - OpenSearch/Elasticsearch syntax for full-text search
  • SQL - Standard SQL for relational queries and analytics
  • PromQL - Prometheus language for time-series and metrics
  • Natural Language - Conversational queries via Fino API

API Operations by Workflow​

Connect​

  • Create connections - Configure connections to external sources
  • List connectors - Browse 50+ available connector types
  • Manage connections - Update credentials, test connectivity, delete connections
  • Browse sources - List datasets from connected data sources

Query​

  • Natural language - Conversational queries via Fino AI
    • WebSocket: GET /fino/nl
    • Threads: GET/POST /fino/threads
    • Messages: POST /fino/message
  • SQL - Execute SQL queries with GET/POST /sql
  • Query DSL - Search with GET /{dataset}/querydsl
  • PromQL - Time-series queries with GET/POST /promql/query

Correlate​

  • List datasets - GET /metadata to list all your datasets
  • Dataset info - GET /{dataset}/metadata for specific dataset stats
  • Create dataset - PUT /{dataset} to create new dataset
  • Upload records - POST /{dataset}/json to add data
  • Delete dataset - DELETE /{dataset} to remove dataset
  • Dataset enrichment - POST /{dataset}/enrich_dataset for data enrichment

Govern​

  • User management - Create and manage user accounts with /user/{name}
  • Role assignment - Define and assign roles with /role/{name}
  • Permissions - Fine-grained RBAC at dataset/record/field levels
  • Key rotation - Rotate API credentials with /user/{name}/keys
  • Authentication - API key rotation and management
  • Audit logs - Track access for agents and humans

API Categories​

The Infino API is organized to support the platform workflow:

  • Core Concepts - Authentication and API conventions
  • Connect - Create and manage connections to your data sources
  • Query - Fino AI, SQL, Query DSL, and PromQL interfaces
  • Correlate - Datasets and data operations
  • Govern - User and permission management
  • Client SDKs - Python SDK for programmatic access

Example Workflows​

Workflow 1: Query data source​

# 1. Create connection to Elasticsearch
POST /source/elasticsearch
{
  "name": "Production Cluster",
  "config": { "host": "https://es.example.com:9200", ... }
}

# 2. Query external data directly
POST /sql
Header: x-infino-connection-id: conn_abc123
{ "query": "SELECT * FROM logs WHERE level='ERROR' LIMIT 10" }

Workflow 2: Natural Language with Fino AI​

# 1. Create conversation thread
POST /fino/threads
{ "name": "Sales Analysis" }

# 2. Connect via WebSocket and ask questions
# Fino queries external sources or datasets automatically

Workflow 3: Govern Agent Access​

# 1. Create role with limited permissions
PUT /role/readonly-analyst
Content-Type: application/yaml

Version: 2025-01-01
Permissions:
  - ResourceType: record
    Actions: [read]
    Resources: ["logs-*", "metrics-*"]

# 2. Create user and assign role
PUT /user/analytics-agent
Content-Type: application/yaml

Version: 2025-01-01
Password: SecureP@ssw0rd2024!
Roles:
  - readonly-analyst

# Agent can now query with controlled access

Workflow 4: Rotate API Keys​

# Rotate API keys for a user (only the user can rotate their own keys)
PATCH /user/{username}/keys

# Returns new access_key and secret_key

API Standards​

  • Format: JSON request/response
  • Authentication: AWS SigV4 (see Authentication)
  • Status codes: Standard HTTP (2xx success, 4xx error, 5xx server error)
  • Compatibility: OpenSearch/Elasticsearch API compatible
  • Pagination: from/size or Scroll API
  • No rate limits: Optimized for high throughput

API Overview​

The Infino API is organized into several functional areas:

  • Connect API: Manage connections to external data sources
  • Query API: Query and search data
  • Correlate API: Ingest and manage data in datasets
  • Govern API: User and role management

Connect API​

Manage connections to your data sources (Elasticsearch, OpenSearch, Snowflake, etc.).

List Available Source Types​

  • GET /sources
    • List all available connector types

List Connections​

  • GET /sources/connections
    • List all active connections

Create Connection​

  • POST /source/{source_type}
    • Create a new connection to a data source
    • Example: POST /source/elasticsearch

Get Connection​

  • GET /source/{connection_id}
    • Get details of a specific connection

Update Connection​

  • PATCH /source/{connection_id}
    • Update connection configuration

Delete Connection​

  • DELETE /source/{connection_id}
    • Delete a connection

Query Dataset via Connection​

  • GET/POST /source/{connection_id}/{dataset}/dsl
    • Query a data source using QueryDSL

Get Dataset Metadata via Connection​

  • GET/HEAD /source/{connection_id}/{dataset}/metadata
    • Get metadata for a data source

Query API​

Query and search data.

Conversation API​

Manage AI conversation threads and messages.

Natural Language​

  • GET /fino/nl
    • Establish WebSocket connection for AI conversations

Send Message in NL​

  • POST /fino/message
    • Send a message in a conversation

List NL Threads​

  • GET /fino/threads
    • List all conversation threads

Create NL Thread​

  • POST /fino/threads
    • Create a new conversation thread

Get NL Thread​

  • GET /fino/threads/{thread_id}
    • Get thread details

Update NL Thread​

  • PUT/PATCH /fino/threads/{thread_id}
    • Update thread metadata

Delete NL Thread​

  • DELETE /fino/threads/{thread_id}
    • Delete a thread

List NL Messages in Thread​

  • POST /fino/threads/{thread_id}/messages
    • Get messages in a thread

Delete NL Messages in Thread​

  • DELETE /fino/threads/{thread_id}/messages
    • Delete messages from a thread
  • GET /{dataset}/querydsl
    • Search a dataset using Elasticsearch QueryDSL

SQL Query​

  • GET /sql
    • Execute SQL queries across datasets

PromQL Query (Instant)​

  • GET/POST /promql/query
    • Prometheus instant query

PromQL Query (Range)​

  • GET/POST /promql/query_range
    • Prometheus range query

PromQL Labels​

  • GET/POST /promql/labels
    • Get available label names

PromQL Label Values​

  • GET/POST /promql/label/{label_name}/values
    • Get values for a specific label

PromQL Series Query​

  • GET/POST /promql/series
    • Find series matching label matchers

PromQL Build Info​

  • GET/POST /promql/status/buildinfo
    • Get Prometheus build information

Dataset PromQL Query​

  • GET /{dataset}/promql
    • Query metrics for a specific dataset

List All Datasets​

  • GET /metadata
    • List all datasets

Get Dataset Metadata​

  • GET /{dataset}/metadata
    • Get metadata for a specific dataset

Govern API​

Manage users, roles, and permissions.

List Users​

  • GET /users
    • List all users

Get User​

  • GET /user/{name}
    • Get user details

Create User​

  • PUT /user/{name}
    • Create a new user

Update User​

  • PATCH /user/{name}
    • Update user details

Delete User​

  • DELETE /user/{name}
    • Delete a user

Rotate API Keys​

  • PATCH /user/{name}/keys
    • Rotate API keys for a user

List Roles​

  • GET /roles
    • List all roles

Get Role​

  • GET /role/{name}
    • Get role details

Create Role​

  • PUT /role/{name}
    • Create a new role

Update Role​

  • PATCH /role/{name}
    • Update role permissions

Delete Role​

  • DELETE /role/{name}
    • Delete a role

Alerts​

  • POST /alert
    • Create a notification channel (YAML payload with channel_type, webhook, slack, or email blocks)
  • GET /alerts
    • List all channels
  • GET /alert/{channel_id}
    • Retrieve a specific channel
  • PATCH /alert/{channel_id}
    • Update channel configuration (YAML)
  • DELETE /alert/{channel_id}
    • Delete a channel
  • POST /alerts/config
    • Apply a YAML document containing channels, templates, and monitors. Ideal for GitOps workflows; existing IDs are updated and missing ones are created.

Monitors​

  • POST /monitor
    • Create a monitor via YAML (query, schedule, triggers, actions)
  • GET /monitors
    • List monitors
  • GET /monitor/{monitor_id}
    • Fetch monitor details
  • PATCH /monitor/{monitor_id}
    • Update monitor configuration
  • DELETE /monitor/{monitor_id}
    • Remove a monitor
  • POST /monitor/{monitor_id}/execute
    • Execute a monitor immediately. Optional YAML body supports trigger_ids.

Correlate API​

Ingest and manage data in Infino datasets.

Create Dataset​

  • PUT /{dataset}
    • Create a new dataset

Delete Dataset​

  • DELETE /{dataset}
    • Delete a dataset

Delete Records by Query​

  • PATCH /{dataset}
    • Delete records matching a query

Ingest JSON Data​

  • POST /{dataset}/json
    • Bulk upload JSON records using Elasticsearch bulk format (NDJSON)

Ingest Metrics Data​

  • POST /{dataset}/metrics
    • Upload Prometheus-format metrics

Upsert Data via SQL​

  • POST /{dataset}/sql
    • Upsert data using SQL INSERT...ON CONFLICT syntax

Enrich Dataset​

  • POST /{dataset}/enrich_dataset
    • Update enrichment policy for a dataset

Import from Source​

  • PUT /import/{source_type}
    • Trigger data import from a connected source

List Import Jobs​

  • GET /import/jobs
    • List all import jobs

Delete Import Job​

  • DELETE /import/jobs/{job_id}
    • Cancel or delete an import job

Notes​

  1. Authentication: All endpoints require signed requests except those listed in the Authentication section. See the authentication documentation for details on request signing.

  2. Content Types:

    • JSON endpoints accept application/x-ndjson (newline-delimited JSON)
    • SQL endpoints accept application/json or plain text
    • Metrics endpoints accept Prometheus exposition format

  3. Error Handling: Errors follow standard HTTP status codes. 401 for authentication failures, 404 for not found, etc.

  4. Rate Limiting: May be applied based on account quotas and settings.

  5. Versioning: The API version is specified via headers or query parameters. Default version: 2025-06-30.