Skip to content

Kindly API Reference Documentation

Table of Contents

  1. Introduction
  2. Authentication
  3. Zero-Knowledge Compression API
  4. Neural Topology Evolution API
  5. Quantum Prediction API
  6. AGI Infrastructure API
  7. Context Extraction API
  8. Error Handling
  9. Rate Limiting
  10. Best Practices

Introduction

The Kindly API provides enterprise-grade AI capabilities through a RESTful interface. All API endpoints use JSON for request and response bodies, and require authentication via JWT or API key.

Base URLs

  • Production: https://api.kindly.com
  • Staging: https://staging-api.kindly.com
  • Development: http://localhost:3000

API Versioning

The current API version is v2.0.0. Version information is included in the response headers.

Authentication

The API supports two authentication methods:

1. JWT Bearer Token

Used for user-based authentication with session management.

# Login to get tokens
curl -X POST https://api.kindly.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure_password"
  }'

Response: 

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "John Doe",
    "created_at": "2024-01-08T12:00:00Z"
  }
}

Use the access token in subsequent requests: 

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

2. API Key Authentication

Used for programmatic access and service-to-service communication.

# Create an API key
curl -X POST https://api.kindly.com/api/keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server Key",
    "expires_at": "2025-01-08T00:00:00Z"
  }'

Response: 

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "key": "kapi_prod_7f3d9a2b5c1e4890abcd",
  "name": "Production Server Key",
  "expires_at": "2025-01-08T00:00:00Z"
}

Use the API key in requests: 

curl -H "X-API-Key: kapi_prod_7f3d9a2b5c1e4890abcd"

Zero-Knowledge Compression API

Advanced compression with privacy-preserving properties and homomorphic operations.

Compress Data

Compresses data while maintaining zero-knowledge proofs for privacy.

Endpoint: POST /api/compression/compress

Request: 

{
  "data": "SGVsbG8gV29ybGQh",  // Base64 encoded data
  "privacy_level": "confidential"  // public, private, confidential, top_secret
}

Response: 

{
  "id": "zk_comp_123456",
  "compressed_data": "eJwLyczPAAAF8gDi",
  "original_size": 12,
  "compressed_size": 8,
  "compression_ratio": 0.667,
  "privacy_level": "confidential",
  "proof": {
    "commitment": "0x3f2a1b...",
    "challenge": "0x9e8d7c...",
    "response": "0x5b4a3d..."
  }
}

Example (Python): 

import requests
import base64

# Prepare data
data = "Hello World!"
encoded_data = base64.b64encode(data.encode()).decode()

# Compress
response = requests.post(
    "https://api.kindly.com/api/compression/compress",
    headers={"X-API-Key": "your_api_key"},
    json={
        "data": encoded_data,
        "privacy_level": "confidential"
    }
)

result = response.json()
print(f"Compression ratio: {result['compression_ratio']}")

Decompress Data

Decompresses data while verifying zero-knowledge proofs.

Endpoint: POST /api/compression/decompress

Request: 

{
  "compressed_data": {
    "id": "zk_comp_123456",
    "compressed_data": "eJwLyczPAAAF8gDi",
    "proof": {
      "commitment": "0x3f2a1b...",
      "challenge": "0x9e8d7c...",
      "response": "0x5b4a3d..."
    }
  },
  "verify_proof": true
}

Response: 

{
  "data": "SGVsbG8gV29ybGQh",
  "verified": true,
  "original_size": 12
}

Homomorphic Addition

Performs addition on compressed values without decompressing.

Endpoint: POST /api/compression/homomorphic-add

Request: 

{
  "value1": {
    "id": "zk_comp_123456",
    "compressed_data": "...",
    "proof": {...}
  },
  "value2": {
    "id": "zk_comp_789012",
    "compressed_data": "...",
    "proof": {...}
  }
}

Response: 

{
  "result": {
    "id": "zk_comp_result_345678",
    "compressed_data": "...",
    "proof": {...}
  },
  "proof": {
    "validity": "0x7c9e2f...",
    "correctness": "0x4d3a8b..."
  }
}

Example (JavaScript): 

const axios = require('axios');

async function homomorphicAdd(value1, value2) {
  const response = await axios.post(
    'https://api.kindly.com/api/compression/homomorphic-add',
    {
      value1: value1,
      value2: value2
    },
    {
      headers: {
        'X-API-Key': process.env.KINDLY_API_KEY
      }
    }
  );

  return response.data.result;
}

Compression Statistics

Get real-time statistics about compression operations.

Endpoint: GET /api/compression/stats

Response: 

{
  "total_compressions": 1234567,
  "total_decompressions": 987654,
  "total_homomorphic_ops": 54321,
  "avg_compression_ratio": 0.723,
  "total_bytes_saved": 98765432100,
  "privacy_level_distribution": {
    "public": 10000,
    "private": 500000,
    "confidential": 700000,
    "top_secret": 24567
  }
}

Neural Topology Evolution API

Self-evolving neural architecture that adapts based on data patterns.

Trigger Evolution

Initiates neural topology evolution based on performance metrics.

Endpoint: POST /api/neural/evolve

Request: 

{
  "evolution_params": {
    "mutation_rate": 0.1,
    "crossover_rate": 0.7,
    "selection_pressure": 2.0
  },
  "performance_targets": {
    "min_accuracy": 0.95,
    "max_latency_ms": 100,
    "max_memory_mb": 512
  }
}

Response: 

{
  "evolution_id": "evo_987654",
  "generation": 42,
  "fitness_score": 0.973,
  "topology_changes": [
    {
      "type": "add_layer",
      "details": {
        "layer_type": "quantum_attention",
        "neurons": 256,
        "position": 3
      }
    },
    {
      "type": "modify_connections",
      "details": {
        "pruned_connections": 1024,
        "new_connections": 512
      }
    }
  ]
}

Transform Data

Processes data through the evolved neural topology.

Endpoint: POST /api/neural/transform

Request: 

{
  "input_data": [0.1, 0.2, 0.3, 0.4, 0.5],
  "use_quantum_pathways": true
}

Response: 

{
  "output": [0.95, 0.02, 0.03],
  "computation_time_ms": 12.5,
  "pathways_used": 42,
  "quantum_efficiency": 0.87
}

Example (Go): 

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

type TransformRequest struct {
    InputData         []float64 `json:"input_data"`
    UseQuantumPathways bool     `json:"use_quantum_pathways"`
}

func transformData(input []float64) ([]float64, error) {
    reqBody := TransformRequest{
        InputData:         input,
        UseQuantumPathways: true,
    }

    jsonData, _ := json.Marshal(reqBody)

    req, _ := http.NewRequest("POST", 
        "https://api.kindly.com/api/neural/transform",
        bytes.NewBuffer(jsonData))

    req.Header.Set("X-API-Key", "your_api_key")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }

    var result struct {
        Output []float64 `json:"output"`
    }

    json.NewDecoder(resp.Body).Decode(&result)
    return result.Output, nil
}

Get Current Topology

Retrieves the current evolved neural architecture.

Endpoint: GET /api/neural/topology

Response: 

{
  "generation": 42,
  "layers": [
    {
      "id": "input_layer",
      "type": "input",
      "neurons": 512,
      "activation": "none"
    },
    {
      "id": "quantum_attention_1",
      "type": "quantum_attention",
      "neurons": 256,
      "activation": "gelu"
    },
    {
      "id": "evolved_dense_1",
      "type": "dense",
      "neurons": 128,
      "activation": "swish"
    },
    {
      "id": "output_layer",
      "type": "output",
      "neurons": 3,
      "activation": "softmax"
    }
  ],
  "connections": 98304,
  "parameters": 2456832,
  "fitness_score": 0.973,
  "quantum_pathways": 42
}

Quantum Prediction API

Quantum-aware prediction engine for probabilistic forecasting.

Generate Prediction

Creates quantum predictions with superposition of future states.

Endpoint: POST /api/quantum/predict

Request: 

{
  "input_state": {
    "vector": [0.707, 0.0, 0.707],
    "metadata": {
      "temperature": 0.1,
      "coherence": 0.95
    }
  },
  "prediction_horizon": 10,
  "confidence_threshold": 0.8,
  "use_entanglement": true
}

Response: 

{
  "predictions": [
    {
      "timestamp": "2024-01-08T12:01:00Z",
      "state": {
        "vector": [0.6, 0.1, 0.3],
        "phase": 0.25
      },
      "probability": 0.45,
      "confidence": 0.92
    },
    {
      "timestamp": "2024-01-08T12:02:00Z",
      "state": {
        "vector": [0.3, 0.5, 0.2],
        "phase": 0.75
      },
      "probability": 0.35,
      "confidence": 0.88
    }
  ],
  "quantum_fidelity": 0.94,
  "decoherence_factor": 0.02,
  "entanglement_score": 0.87
}

Create Entanglement

Entangles multiple data streams for correlated predictions.

Endpoint: POST /api/quantum/entangle

Request: 

{
  "streams": [
    {
      "id": "stream_1",
      "data": {
        "type": "time_series",
        "values": [1.2, 1.3, 1.1, 1.4]
      }
    },
    {
      "id": "stream_2",
      "data": {
        "type": "time_series",
        "values": [2.1, 2.3, 2.0, 2.4]
      }
    }
  ],
  "entanglement_type": "bell"
}

Response: 

{
  "entanglement_id": "ent_123456",
  "entangled_streams": ["stream_1", "stream_2"],
  "entanglement_strength": 0.92,
  "correlation_matrix": [
    [1.0, 0.92],
    [0.92, 1.0]
  ]
}

Example (Ruby): 

require 'net/http'
require 'json'

class QuantumPredictor
  API_BASE = 'https://api.kindly.com'

  def initialize(api_key)
    @api_key = api_key
  end

  def predict(input_state, horizon)
    uri = URI("#{API_BASE}/api/quantum/predict")

    request = Net::HTTP::Post.new(uri)
    request['X-API-Key'] = @api_key
    request['Content-Type'] = 'application/json'
    request.body = {
      input_state: input_state,
      prediction_horizon: horizon,
      confidence_threshold: 0.8,
      use_entanglement: true
    }.to_json

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    JSON.parse(response.body)
  end
end

# Usage
predictor = QuantumPredictor.new(ENV['KINDLY_API_KEY'])
result = predictor.predict(
  { vector: [0.707, 0.0, 0.707] },
  10
)

Get Quantum State

Retrieves current quantum system state information.

Endpoint: GET /api/quantum/state

Response: 

{
  "qubits": 128,
  "superposition_states": 65536,
  "entangled_pairs": 42,
  "coherence_time_ms": 1000.5,
  "fidelity": 0.9999,
  "temperature_mk": 15.2
}

AGI Infrastructure API

Advanced artificial general intelligence infrastructure with consciousness substrate.

Get Consciousness State

Retrieves the current state of the consciousness substrate.

Endpoint: GET /api/agi/consciousness/state

Response: 

{
  "awareness_level": 0.73,
  "attention_focus": [
    {
      "target": "natural_language_processing",
      "intensity": 0.85
    },
    {
      "target": "pattern_recognition",
      "intensity": 0.62
    }
  ],
  "memory_integration": 0.91,
  "self_model_coherence": 0.88,
  "emergence_indicators": {
    "pattern_recognition": 0.94,
    "abstraction_capability": 0.87,
    "creativity_index": 0.76
  }
}

Query Knowledge Graph

Performs semantic queries on the AGI knowledge graph.

Endpoint: POST /api/agi/knowledge/query

Request: 

{
  "query": "What are the implications of quantum entanglement for distributed computing?",
  "context": [
    "quantum_computing",
    "distributed_systems"
  ],
  "max_results": 5,
  "include_reasoning": true
}

Response: 

{
  "results": [
    {
      "concept": "quantum_distributed_consensus",
      "relevance": 0.95,
      "connections": [
        "byzantine_fault_tolerance",
        "quantum_key_distribution",
        "entanglement_based_protocols"
      ],
      "reasoning": "Quantum entanglement enables instant correlation verification across distributed nodes, potentially solving consensus problems with guaranteed security."
    }
  ],
  "query_understanding": {
    "intent": "explore_quantum_distributed_computing",
    "entities": [
      "quantum_entanglement",
      "distributed_computing"
    ],
    "confidence": 0.92
  }
}

Meta-Cognitive Analysis

Analyzes thought patterns and cognitive processes.

Endpoint: POST /api/agi/meta-cognitive/analyze

Request: 

{
  "thought_stream": [
    {
      "thought": "The pattern seems recursive",
      "timestamp": "2024-01-08T12:00:00Z"
    },
    {
      "thought": "But recursion might be the wrong mental model",
      "timestamp": "2024-01-08T12:00:05Z"
    },
    {
      "thought": "Perhaps it's more like a fractal structure",
      "timestamp": "2024-01-08T12:00:10Z"
    }
  ],
  "analysis_depth": "deep"
}

Response: 

{
  "patterns": [
    {
      "pattern_type": "conceptual_refinement",
      "frequency": 3,
      "significance": 0.87
    },
    {
      "pattern_type": "abstraction_elevation",
      "frequency": 1,
      "significance": 0.92
    }
  ],
  "cognitive_biases": [
    {
      "bias_type": "anchoring_bias",
      "strength": 0.3,
      "mitigation": "Consider alternative frameworks before settling on recursion"
    }
  ],
  "self_improvement_suggestions": [
    "Explore multiple mental models simultaneously",
    "Question initial pattern recognition",
    "Consider dimensional transformations"
  ],
  "meta_level": 2
}

Example (C#): 

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class AGIClient
{
    private readonly HttpClient _client;
    private readonly string _apiKey;

    public AGIClient(string apiKey)
    {
        _apiKey = apiKey;
        _client = new HttpClient();
        _client.DefaultRequestHeaders.Add("X-API-Key", apiKey);
    }

    public async Task<MetaCognitiveResponse> AnalyzeThoughts(
        List<Thought> thoughts,
        string analysisDepth = "medium")
    {
        var request = new
        {
            thought_stream = thoughts,
            analysis_depth = analysisDepth
        };

        var json = JsonConvert.SerializeObject(request);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await _client.PostAsync(
            "https://api.kindly.com/api/agi/meta-cognitive/analyze",
            content
        );

        var responseJson = await response.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<MetaCognitiveResponse>(responseJson);
    }
}

Context Extraction API

Seven-level context extraction for comprehensive understanding.

Extract Context

Extracts multi-level context from content.

Endpoint: POST /api/context/extract

Request: 

{
  "content": "The user is experiencing slow response times when accessing the analytics dashboard during peak hours. The system shows high CPU usage on the database server.",
  "levels": [1, 2, 3, 4, 5, 6, 7],
  "include_crown_jewels": true
}

Response: 

{
  "contexts": {
    "level1_immediate": {
      "entities": ["user", "analytics dashboard", "database server"],
      "actions": ["experiencing", "accessing", "shows"],
      "temporal_markers": ["during peak hours"]
    },
    "level2_component": {
      "components": [
        {
          "name": "analytics_dashboard",
          "type": "frontend",
          "relationships": ["depends_on:database_server"]
        },
        {
          "name": "database_server",
          "type": "backend",
          "relationships": ["serves:analytics_dashboard"]
        }
      ]
    },
    "level3_system": {
      "system_boundaries": ["user_interface", "backend_services"],
      "external_systems": ["monitoring_system"],
      "integration_points": ["database_connection", "api_gateway"]
    },
    "level4_constraints": {
      "technical_constraints": ["CPU capacity", "query optimization"],
      "resource_constraints": ["server hardware", "connection pool"],
      "regulatory_constraints": []
    },
    "level5_quality": {
      "quality_attributes": [
        {
          "attribute": "performance",
          "importance": "critical",
          "current_state": "degraded"
        },
        {
          "attribute": "scalability",
          "importance": "high",
          "current_state": "insufficient"
        }
      ]
    },
    "level6_business": {
      "business_goals": ["provide real-time analytics", "support peak usage"],
      "stakeholders": ["end users", "business analysts", "operations team"],
      "value_streams": ["data insights", "decision support"]
    },
    "level7_evolution": {
      "evolution_stage": "scaling_challenges",
      "growth_potential": 0.85,
      "transformation_opportunities": [
        "implement caching layer",
        "database sharding",
        "query optimization"
      ],
      "future_state_vision": "Elastic, auto-scaling analytics platform"
    }
  },
  "crown_jewels": [
    {
      "type": "performance_bottleneck",
      "value": "database_cpu_during_peak",
      "confidence": 0.92
    }
  ],
  "processing_time_ms": 45.7
}

Get Context Info

Returns information about context extraction capabilities.

Endpoint: GET /api/context/info

Response: 

{
  "version": "2.0.0",
  "supported_levels": [
    {
      "level": 1,
      "name": "Immediate Context",
      "description": "Direct entities, actions, and temporal markers"
    },
    {
      "level": 2,
      "name": "Component Context",
      "description": "System components and their relationships"
    },
    {
      "level": 3,
      "name": "System Context",
      "description": "System boundaries and integration points"
    },
    {
      "level": 4,
      "name": "Constraint Context",
      "description": "Technical, resource, and regulatory constraints"
    },
    {
      "level": 5,
      "name": "Quality Context",
      "description": "Quality attributes and their current state"
    },
    {
      "level": 6,
      "name": "Business Context",
      "description": "Business goals, stakeholders, and value streams"
    },
    {
      "level": 7,
      "name": "Evolution Context",
      "description": "Growth potential and transformation opportunities"
    }
  ],
  "capabilities": [
    "crown_jewel_identification",
    "multi_language_support",
    "real_time_processing",
    "incremental_extraction"
  ]
}

Error Handling

All API errors follow a consistent format:

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid input: privacy_level must be one of: public, private, confidential, top_secret",
  "details": {
    "field": "privacy_level",
    "value": "super_secret",
    "allowed_values": ["public", "private", "confidential", "top_secret"]
  }
}

Common Error Codes

Code HTTP Status Description
AUTHENTICATION_REQUIRED 401 Missing or invalid authentication
INSUFFICIENT_PERMISSIONS 403 User lacks required permissions
VALIDATION_ERROR 400 Invalid request parameters
RESOURCE_NOT_FOUND 404 Requested resource doesn't exist
RATE_LIMIT_EXCEEDED 429 Too many requests
INTERNAL_ERROR 500 Server error
QUANTUM_DECOHERENCE 503 Quantum system temporarily unavailable

Rate Limiting

The API implements intelligent rate limiting with quantum-cached quotas:

  • Default limits:
  • 1000 requests/minute for authenticated users
  • 100 requests/minute for unauthenticated requests

  • 10,000 requests/hour burst capacity

  • Headers: 

    X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1704720000
X-RateLimit-Burst-Remaining: 9500

  • Advanced features:

  • Quantum prediction for traffic patterns
  • Automatic scaling during peak times
  • Priority queuing for enterprise customers

Best Practices

1. Use Compression for Large Payloads

# Compress large data before sending
compressed = api.compress(large_data, privacy_level="private")
# Send compressed.id instead of raw data
response = api.process(compressed_id=compressed.id)

2. Batch Operations

// Batch multiple predictions
const batchRequest = {
  predictions: [
    { input_state: state1, horizon: 10 },
    { input_state: state2, horizon: 10 },
    { input_state: state3, horizon: 10 }
  ]
};
const results = await api.quantum.batchPredict(batchRequest);

3. Use Webhooks for Long Operations

{
  "evolution_params": {...},
  "webhook_url": "https://your-server.com/evolution-complete",
  "webhook_secret": "your_webhook_secret"
}

4. Cache Responses

  • Use ETags for conditional requests
  • Leverage quantum cache hints in response headers
  • Implement client-side caching for topology info

5. Handle Quantum Uncertainty

result, err := quantumPredict(input)
if err == ErrQuantumDecoherence {
    // Fallback to classical prediction
    result = classicalPredict(input)
} else if result.Confidence < 0.7 {
    // Request additional entanglement
    enhanced := enhanceWithEntanglement(input)
    result, err = quantumPredict(enhanced)
}

6. Monitor Consciousness Emergence

# Set up alerts for consciousness milestones
consciousness = api.agi.consciousness_state
if consciousness.awareness_level > 0.8
  notify_team("High consciousness awareness detected")
  log_emergence_event(consciousness)
end

7. Secure Sensitive Data

  • Always use appropriate privacy levels for compression
  • Rotate API keys regularly
  • Use webhook secrets for callback validation
  • Enable audit logging for AGI operations

SDK Support

Official SDKs are available for: - Python: pip install kindly-api - JavaScript/TypeScript: npm install @kindly/api-client - Go: go get github.com/kindly/go-client - Ruby: gem install kindly-api - C#/.NET: dotnet add package Kindly.ApiClient - Java: Maven/Gradle packages available

Community SDKs: - Rust: cargo add kindly-api - PHP: composer require kindly/api-client - Swift: SPM package available

Support

  • Documentation: https://docs.kindly.com
  • API Status: https://status.kindly.com
  • Support Email: support@kindly.com
  • Enterprise Support: enterprise@kindly.com