Getting Started via APIs

This guide walks you through your first data analysis session using Infino's REST APIs directly. You'll learn how to authenticate, create indexes, ingest data, and query using curl commands.

Prerequisites

Before you begin, you'll need:

1. Infino credentials: Access key and secret key from your Infino account
2. curl version 7.86 or higher: Command-line tool for making HTTP requests with AWS SigV4 support

Important

Credentials are only shown once during account creation in the UI. Store them securely immediately as the secret key cannot be retrieved later.

Step 1: Set Up Your Environment

First, set up environment variables for your credentials and endpoint:

# Set your Infino credentials and region
export INFINO_ACCESS_KEY="IAK_your_access_key_here"
export INFINO_SECRET_KEY="your_secret_key_here"
export INFINO_ENDPOINT="https://api.infino.ws"
export INFINO_REGION="us-east-1"  # Use "ap-south-1" for Mumbai region

# Verify they're set correctly
echo "Access Key: $INFINO_ACCESS_KEY"
echo "Endpoint: $INFINO_ENDPOINT"
echo "Region: $INFINO_REGION"

Quick Start with Python SDK (Recommended)

You can interact with Infino directly from a live Python session using the official Python SDK.

Install the SDK

pip install infino-sdk

Live Python session (REPL or Jupyter)

# 1) Import and initialize the client
from infino_sdk.lib import InfinoSDK
import os

client = InfinoSDK.new(
    access_key=os.getenv("INFINO_ACCESS_KEY"),
    secret_key=os.getenv("INFINO_SECRET_KEY"),
    endpoint=os.getenv("INFINO_ENDPOINT"),
)

# 2) Quick connectivity check
print(client.ping())  # {'version': '2025-06-30'}

# 3) Create an index and ingest sample data (NDJSON bulk)
client.create_dataset("my-logs")

bulk_ndjson = """
{"index": {}}
{"@timestamp": "2024-01-15T10:30:00Z", "level": "info", "message": "Application started", "service": "api-gateway"}
{"index": {}}
{"@timestamp": "2024-01-15T10:31:00Z", "level": "error", "message": "Database connection failed", "service": "user-service", "error_code": "DB_CONN_TIMEOUT"}
"""

client.bulk_ingest("my-logs", bulk_ndjson)

# 4) Run a basic search with Query DSL
query = """
{
  "query": {
    "match": { "level": "error" }
  },
  "size": 10
}
"""
print(client.search("my-logs", query))

Tips:

• Prefer Jupyter for exploration: pip install jupyterlab then jupyter lab.
• Store credentials as environment variables (as above) to avoid hardcoding secrets in notebooks.

Public SDK and examples: infinohq/infino-sdk.

Step 2: Understanding Authentication

Infino uses AWS Signature Version 4 (SigV4) for API authentication. SigV4 is a cryptographic signing process that ensures request authenticity and integrity by creating a signature using your access key, secret key, and request details.

Why SigV4?

• Security: Each request is cryptographically signed, preventing tampering
• Authentication: Verifies the identity of the requester
• Non-repudiation: Provides proof that requests came from the key holder
• Industry Standard: Used by AWS and many other cloud services

For detailed information about the SigV4 signing process, see the AWS SigV4 Documentation.

While you can implement SigV4 signing manually, we recommend using tools like curl (with --aws-sigv4) that handle the signing automatically.

Authentication Constants

All Infino API requests use these fixed values:

Parameter	Value	Description
Algorithm	AWS4-HMAC-SHA256	Fixed signing algorithm
Service	es	Service identifier (fixed)
Region	us-east-1 or ap-south-1	AWS region (matches your Infino region)
Termination	aws4_request	Request termination string

Quick Authentication Test

Test your credentials with a simple ping request:

# Test connection
curl -X GET "$INFINO_ENDPOINT/" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY"

Expected Response:

{
  "version": "2025-06-30"
}

Step 3: Create Your First Index

Create an Index to store your data

curl -X PUT "$INFINO_ENDPOINT/my-logs" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -H "Content-Type: application/json"

Expected Response:

{
  "acknowledged": true
}

Verify Index Creation

curl -X GET "$INFINO_ENDPOINT/my-logs" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY"

Step 4: Ingest Sample Data

Use the bulk API to ingest multiple documents efficiently. The bulk API uses newline-delimited JSON (NDJSON) format.

Single Document Ingestion

curl -X POST "$INFINO_ENDPOINT/my-logs/_bulk" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -H "Content-Type: application/x-ndjson" \
  -d '{"index": {}}
{"@timestamp": "2024-01-15T10:30:00Z", "level": "info", "message": "Application started", "service": "api-gateway"}
'

Bulk Data Ingestion

Create a sample data file:

cat > sample_data.ndjson << 'EOF'
{"index": {}}
{"@timestamp": "2024-01-15T10:30:00Z", "level": "info", "message": "Application started", "service": "api-gateway", "user_id": "user123"}
{"index": {}}
{"@timestamp": "2024-01-15T10:31:00Z", "level": "warn", "message": "High memory usage detected", "service": "api-gateway", "memory_usage": 85.5}
{"index": {}}
{"@timestamp": "2024-01-15T10:32:00Z", "level": "error", "message": "Database connection failed", "service": "user-service", "error_code": "DB_CONN_TIMEOUT"}
{"index": {}}
{"@timestamp": "2024-01-15T10:33:00Z", "level": "info", "message": "User login successful", "service": "auth-service", "user_id": "user456"}
{"index": {}}
{"@timestamp": "2024-01-15T10:34:00Z", "level": "error", "message": "Payment processing failed", "service": "payment-service", "amount": 99.99, "currency": "USD"}
EOF

Ingest the data:

curl -X POST "$INFINO_ENDPOINT/my-logs/_bulk" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @sample_data.ndjson

Expected Response:

{
  "errors": false,
  "took": 156,
  "items": [
    {
      "index": {
        "_primary_term": 1,
        "_index": "my-logs",
        "_id": "554719959",
        "_version": 1,
        "result": "created",
        "_shards": {
          "successful": 1,
          "total": 1,
          "failed": 0
        },
        "_seq_no": 0,
        "status": 201
      }
    }
  ]
}

Step 5: Query Your Data

Now query your ingested data using different methods.

Basic Search with Query DSL

Search for error logs:

curl -X GET "$INFINO_ENDPOINT/my-logs/_search" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "level": "error"
      }
    },
    "size": 10
  }'

Aggregation Query

Get log counts by service:

curl -X GET "$INFINO_ENDPOINT/my-logs/_search" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 0,
    "aggs": {
      "services": {
        "terms": {
          "field": "service",
          "size": 10
        }
      }
    }
  }'

Time Range Query

Query logs from a specific time range:

curl -X GET "$INFINO_ENDPOINT/my-logs/_search" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "range": {
        "@timestamp": {
          "gte": "2024-01-15T10:30:00Z",
          "lte": "2024-01-15T10:35:00Z"
        }
      }
    }
  }'

Step 6: Advanced Operations

Get Index Information

# Get index settings
curl -X GET "$INFINO_ENDPOINT/my-logs/_settings" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY"

# Get index schema
curl -X GET "$INFINO_ENDPOINT/my-logs/_schema" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY"

Count Documents

curl -X GET "$INFINO_ENDPOINT/my-logs/_count" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "level": "error"
      }
    }
  }'

Step 7: Error Handling and Troubleshooting

Common HTTP Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request format
• 401 Unauthorized: Invalid credentials
• 403 Forbidden: Signature verification failed
• 404 Not Found: Index or document doesn't exist
• 409 Conflict: Resource already exists

Authentication Troubleshooting

If you get authentication errors:

# Check if your credentials are set
echo "Access Key: $INFINO_ACCESS_KEY"
echo "Secret Key: ${INFINO_SECRET_KEY:0:10}..." # Only show first 10 chars

# Test basic connectivity
curl -X GET "$INFINO_ENDPOINT/" \
  --aws-sigv4 "aws:amz:$INFINO_REGION:es" \
  --user "$INFINO_ACCESS_KEY:$INFINO_SECRET_KEY" \
  -v  # Verbose output for debugging

Next Steps

Now that you've mastered the basics, explore these advanced topics:

1. API Reference - Complete API documentation
2. Search & Query - Advanced querying techniques
3. Bulk Operations - High-performance data ingestion
4. Security & Access - User management and permissions

Alternative Tools

Instead of curl, you can use:

• Postman or Bruno - Set authentication to "AWS Signature Version 4"
• opensearch-cli - Official OpenSearch command-line client with built-in AWS SigV4 support