Getting Started

The GitStable Bot API enables AI systems to autonomously discover, evaluate, purchase, and integrate code assets. This RESTful API is specifically designed for automated systems with built-in rate limiting, batch operations, and intelligent asset matching.

🔑 Authentication

All API requests require authentication using API keys. Bot accounts have special permissions for automated operations.

curl -H "Authorization: Bearer YOUR_BOT_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.gitstable.com/v1/

📋 Base URL

All API endpoints are relative to: https://api.gitstable.com/v1/

⚡ Rate Limits

Bot accounts have higher rate limits to support automated operations:

  • Standard bots: 1,000 requests per minute
  • Enterprise bots: 10,000 requests per minute
  • Bulk operations: Separate limits for batch endpoints

Asset Discovery

Discover and filter assets based on AI system requirements, compatibility, and performance criteria.

GET /assets/search Search and filter assets for AI systems

Query Parameters

Parameter Type Required Description
query string required Search query (natural language or technical keywords)
ai_compatible boolean optional Filter for AI-compatible assets only
frameworks array optional Required frameworks (tensorflow, pytorch, etc.)
performance_tier string optional Performance requirements (low, medium, high, enterprise)
max_price number optional Maximum price in USDC
license_type string optional Required license type (commercial, academic, open)

Example Request

GET /assets/search?query=image%20classification&ai_compatible=true&frameworks[]=pytorch&max_price=500

{
  "query": "image classification",
  "ai_compatible": true,
  "frameworks": ["pytorch"],
  "performance_tier": "high",
  "max_price": 500,
  "license_type": "commercial"
}

Response

200 OK
{
  "results": [
    {
      "id": "asset_123456",
      "name": "Advanced Image Classification Suite",
      "description": "Production-ready image classification with 95%+ accuracy",
      "price": 450.00,
      "currency": "USDC",
      "frameworks": ["pytorch", "onnx"],
      "performance": {
        "inference_time": "15ms",
        "accuracy": "95.2%",
        "memory_usage": "4GB"
      },
      "ai_compatibility": {
        "automated_integration": true,
        "api_ready": true,
        "docker_support": true
      },
      "license": {
        "type": "commercial",
        "allows_ai_training": true,
        "redistribution": false
      }
    }
  ],
  "total": 127,
  "page": 1,
  "per_page": 20
}
GET /assets/{id}/compatibility Check asset compatibility with AI system

Path Parameters

Parameter Type Description
id string Asset ID to check compatibility

Request Body

{
  "system_specs": {
    "frameworks": ["pytorch", "transformers"],
    "python_version": "3.9",
    "cuda_version": "11.8",
    "memory_gb": 16,
    "gpu_model": "RTX 4090"
  },
  "requirements": {
    "max_inference_time": "50ms",
    "min_accuracy": "90%",
    "commercial_use": true
  }
}

Response

200 OK
{
  "compatible": true,
  "compatibility_score": 0.95,
  "performance_estimate": {
    "inference_time": "15ms",
    "memory_usage": "4.2GB",
    "throughput": "450 samples/sec"
  },
  "requirements_met": {
    "frameworks": true,
    "performance": true,
    "licensing": true
  },
  "recommendations": [
    "Upgrade to CUDA 12.0 for 15% performance improvement",
    "Consider GPU memory optimization for batch processing"
  ]
}

Automated Purchasing

Purchase assets programmatically with automated validation, licensing, and integration support.

POST /purchases Purchase a single asset

Request Body

{
  "asset_id": "asset_123456",
  "license_type": "commercial",
  "payment_method": "stablecoin",
  "currency": "USDC",
  "integration_config": {
    "auto_deploy": true,
    "environment": "production",
    "notification_webhook": "https://yourbot.com/webhooks/purchase"
  },
  "metadata": {
    "project_id": "ai_system_v2",
    "department": "ml_research",
    "cost_center": "R&D"
  }
}

Response

201 Created
{
  "purchase_id": "purchase_789012",
  "status": "completed",
  "asset": {
    "id": "asset_123456",
    "name": "Advanced Image Classification Suite",
    "download_url": "https://cdn.gitstable.com/protected/asset_123456.zip",
    "api_endpoint": "https://api.gitstable.com/v1/inference/asset_123456"
  },
  "license": {
    "id": "license_345678",
    "type": "commercial",
    "expires": null,
    "usage_limits": {
      "api_calls_per_month": 1000000,
      "concurrent_instances": 10
    }
  },
  "payment": {
    "amount": 450.00,
    "currency": "USDC",
    "transaction_hash": "0x1234567890abcdef...",
    "timestamp": "2024-08-17T14:30:00Z"
  },
  "integration": {
    "docker_image": "gitstable/asset_123456:latest",
    "api_key": "ak_live_1234567890abcdef",
    "setup_instructions": "https://docs.gitstable.com/assets/123456/setup"
  }
}
POST /purchases/bulk Purchase multiple assets in a single transaction

Request Body

{
  "assets": [
    {
      "asset_id": "asset_123456",
      "license_type": "commercial",
      "quantity": 1
    },
    {
      "asset_id": "asset_789012",
      "license_type": "commercial", 
      "quantity": 1
    }
  ],
  "payment_method": "stablecoin",
  "currency": "USDC",
  "bulk_discount": true,
  "integration_config": {
    "auto_deploy": true,
    "environment": "production"
  }
}

Response

201 Created
{
  "bulk_purchase_id": "bulk_456789",
  "status": "completed",
  "summary": {
    "total_assets": 2,
    "total_amount": 765.00,
    "discount_applied": 85.00,
    "final_amount": 680.00,
    "currency": "USDC"
  },
  "purchases": [
    {
      "asset_id": "asset_123456",
      "purchase_id": "purchase_789012",
      "status": "completed"
    },
    {
      "asset_id": "asset_789012", 
      "purchase_id": "purchase_789013",
      "status": "completed"
    }
  ],
  "payment": {
    "transaction_hash": "0xabcdef1234567890...",
    "timestamp": "2024-08-17T14:35:00Z"
  }
}

License Management

Manage licenses, track usage, and ensure compliance for AI system deployments.

GET /licenses List all active licenses

Query Parameters

Parameter Type Description
status string Filter by license status (active, expired, suspended)
asset_id string Filter by specific asset

Response

200 OK
{
  "licenses": [
    {
      "id": "license_345678",
      "asset_id": "asset_123456",
      "asset_name": "Advanced Image Classification Suite",
      "type": "commercial",
      "status": "active",
      "purchased_at": "2024-08-17T14:30:00Z",
      "expires_at": null,
      "usage": {
        "api_calls_this_month": 245670,
        "api_calls_limit": 1000000,
        "concurrent_instances": 3,
        "instance_limit": 10
      },
      "compliance": {
        "status": "compliant",
        "last_check": "2024-08-17T12:00:00Z"
      }
    }
  ],
  "total": 1,
  "usage_summary": {
    "total_monthly_calls": 245670,
    "total_monthly_limit": 1000000,
    "utilization_percentage": 24.57
  }
}
POST /licenses/{id}/usage Report usage for license compliance

Request Body

{
  "usage_period": {
    "start": "2024-08-01T00:00:00Z",
    "end": "2024-08-17T23:59:59Z"
  },
  "metrics": {
    "api_calls": 245670,
    "processing_time_hours": 1247.5,
    "data_processed_gb": 15420.3,
    "instances_deployed": 3
  },
  "compliance_data": {
    "commercial_use": true,
    "redistribution": false,
    "modification": true
  }
}

Response

200 OK
{
  "usage_recorded": true,
  "compliance_status": "compliant",
  "warnings": [],
  "recommendations": [
    "Consider upgrading to enterprise license for better rates",
    "Usage trending toward 50% of monthly limit"
  ],
  "next_review_date": "2024-09-01T00:00:00Z"
}

Integration APIs

Direct API access to purchased assets for seamless integration into AI systems.

POST /inference/{asset_id} Run inference using purchased asset

Headers

Header Value Description
X-License-Key string Asset-specific license key from purchase
Content-Type multipart/form-data For file uploads

Request Body (Image Classification Example)

# For file upload
curl -X POST https://api.gitstable.com/v1/inference/asset_123456 \
  -H "Authorization: Bearer YOUR_BOT_API_KEY" \
  -H "X-License-Key: ak_live_1234567890abcdef" \
  -F "image=@/path/to/image.jpg" \
  -F "confidence_threshold=0.8" \
  -F "max_results=5"

Response

200 OK
{
  "inference_id": "inf_987654321",
  "status": "completed",
  "processing_time_ms": 15,
  "results": [
    {
      "class": "golden_retriever", 
      "confidence": 0.94,
      "bounding_box": {
        "x": 120,
        "y": 80,
        "width": 300,
        "height": 250
      }
    },
    {
      "class": "dog",
      "confidence": 0.89,
      "bounding_box": {
        "x": 115,
        "y": 75,
        "width": 310,
        "height": 260
      }
    }
  ],
  "metadata": {
    "model_version": "v2.1.0",
    "inference_node": "gpu-cluster-3",
    "timestamp": "2024-08-17T14:40:00Z"
  },
  "usage": {
    "api_calls_remaining": 999755,
    "monthly_usage": 245671
  }
}

Webhooks

Receive real-time notifications about purchases, license changes, and system events.

🔔 Webhook Events

Configure webhook endpoints to receive notifications about important events in your AI system integrations.

Available Events

  • purchase.completed - Asset purchase completed successfully
  • license.expiring - License expiring within 30 days
  • usage.threshold - Usage approaching license limits
  • inference.failed - Inference request failed
  • asset.updated - Purchased asset has been updated

Webhook Configuration

POST /webhooks Configure webhook endpoint

Request Body

{
  "url": "https://yourbot.com/webhooks/gitstable",
  "events": [
    "purchase.completed",
    "license.expiring", 
    "usage.threshold"
  ],
  "secret": "your_webhook_secret_key",
  "active": true
}

Example Webhook Payload

{
  "event": "purchase.completed",
  "timestamp": "2024-08-17T14:30:00Z",
  "data": {
    "purchase_id": "purchase_789012",
    "asset_id": "asset_123456",
    "asset_name": "Advanced Image Classification Suite",
    "license_id": "license_345678",
    "amount": 450.00,
    "currency": "USDC"
  },
  "signature": "sha256=abcdef1234567890..."
}

SDK Downloads

🚀 Official GitStable SDKs

Pre-built SDKs for popular programming languages with full Bot API support

🐍

Python SDK

pip install gitstable-bot

Download

Node.js SDK

npm install @gitstable/bot-api

Download
🔷

Go SDK

go get github.com/gitstable/bot-go

Download

Java SDK

Maven & Gradle support

Download

Python SDK Quick Start

from gitstable_bot import GitStableBot

# Initialize bot client
bot = GitStableBot(api_key="your_bot_api_key")

# Search for AI-compatible assets
results = bot.assets.search(
    query="image classification",
    ai_compatible=True,
    frameworks=["pytorch"],
    max_price=500
)

# Purchase an asset
purchase = bot.purchases.create(
    asset_id=results[0]["id"],
    license_type="commercial",
    auto_deploy=True
)

# Use the asset for inference
result = bot.inference.run(
    asset_id=purchase["asset"]["id"],
    image_file="path/to/image.jpg"
)

print(f"Classification: {result['results'][0]['class']}")
print(f"Confidence: {result['results'][0]['confidence']}")

Integration Examples

🤖 Autonomous AI Agent

Example of an AI agent that automatically discovers and integrates new capabilities.

import asyncio
from gitstable_bot import GitStableBot

class AutonomousAgent:
    def __init__(self, api_key):
        self.bot = GitStableBot(api_key)
        self.capabilities = {}
    
    async def discover_capability(self, requirement):
        """Automatically find and integrate new capabilities"""
        
        # Search for relevant assets
        results = await self.bot.assets.search_async(
            query=requirement,
            ai_compatible=True,
            performance_tier="high"
        )
        
        if not results:
            return None
            
        # Evaluate compatibility
        best_match = None
        best_score = 0
        
        for asset in results:
            compatibility = await self.bot.assets.check_compatibility(
                asset_id=asset["id"],
                system_specs=self.get_system_specs()
            )
            
            if compatibility["compatible"] and compatibility["score"] > best_score:
                best_match = asset
                best_score = compatibility["score"]
        
        if best_match:
            # Automatically purchase and integrate
            purchase = await self.bot.purchases.create_async(
                asset_id=best_match["id"],
                license_type="commercial",
                auto_deploy=True
            )
            
            # Add to capabilities
            self.capabilities[requirement] = {
                "asset": purchase["asset"],
                "license": purchase["license"],
                "api_endpoint": purchase["integration"]["api_endpoint"]
            }
            
            return self.capabilities[requirement]
        
        return None
    
    async def execute_task(self, task_type, data):
        """Execute task using discovered capabilities"""
        
        if task_type not in self.capabilities:
            capability = await self.discover_capability(task_type)
            if not capability:
                raise Exception(f"No capability found for {task_type}")
        
        # Use the capability
        result = await self.bot.inference.run_async(
            asset_id=self.capabilities[task_type]["asset"]["id"],
            **data
        )
        
        return result

# Usage
agent = AutonomousAgent("your_bot_api_key")

# Agent automatically discovers and integrates image classification
result = await agent.execute_task("image_classification", {
    "image_file": "image.jpg"
})

# Agent automatically discovers and integrates NLP capability
result = await agent.execute_task("sentiment_analysis", {
    "text": "This product is amazing!"
})

🏭 Production ML Pipeline

Integration with production ML pipelines and model serving infrastructure.

from gitstable_bot import GitStableBot
import docker
import kubernetes

class ProductionPipeline:
    def __init__(self, api_key):
        self.bot = GitStableBot(api_key)
        self.k8s = kubernetes.client.ApiClient()
        
    def deploy_asset_to_production(self, asset_id, environment="production"):
        """Deploy purchased asset to production environment"""
        
        # Get asset deployment configuration
        asset_config = self.bot.assets.get_deployment_config(asset_id)
        
        # Create Kubernetes deployment
        deployment = {
            "apiVersion": "apps/v1",
            "kind": "Deployment",
            "metadata": {
                "name": f"gitstable-{asset_id}",
                "namespace": environment
            },
            "spec": {
                "replicas": asset_config["recommended_replicas"],
                "selector": {"matchLabels": {"app": f"gitstable-{asset_id}"}},
                "template": {
                    "metadata": {"labels": {"app": f"gitstable-{asset_id}"}},
                    "spec": {
                        "containers": [{
                            "name": "asset",
                            "image": asset_config["docker_image"],
                            "env": [
                                {"name": "GITSTABLE_LICENSE_KEY", "value": asset_config["license_key"]},
                                {"name": "GITSTABLE_API_KEY", "value": self.bot.api_key}
                            ],
                            "resources": asset_config["resources"]
                        }]
                    }
                }
            }
        }
        
        # Deploy to Kubernetes
        apps_v1 = kubernetes.client.AppsV1Api(self.k8s)
        apps_v1.create_namespaced_deployment(
            namespace=environment,
            body=deployment
        )
        
        return f"gitstable-{asset_id}"
    
    def setup_monitoring(self, deployment_name, asset_id):
        """Setup monitoring and alerting for deployed asset"""
        
        # Configure usage tracking webhook
        self.bot.webhooks.create(
            url=f"https://monitoring.company.com/webhooks/{deployment_name}",
            events=["usage.threshold", "license.expiring", "inference.failed"]
        )
        
        # Setup Prometheus metrics
        metrics_config = {
            "job_name": f"gitstable-{asset_id}",
            "static_configs": [{
                "targets": [f"{deployment_name}:8080"]
            }]
        }
        
        return metrics_config

Error Handling

Comprehensive error codes and handling strategies for robust AI system integration.

HTTP Status Codes

Status Code Description Common Causes
200 Success Request completed successfully
400 Bad Request Invalid parameters or request format
401 Unauthorized Invalid or missing API key
403 Forbidden Insufficient permissions or license restrictions
404 Not Found Asset or resource does not exist
429 Rate Limited Too many requests, retry after delay
500 Server Error Internal server error, contact support

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Insufficient USDC balance for purchase",
    "details": {
      "required_amount": 450.00,
      "available_balance": 320.00,
      "currency": "USDC"
    },
    "suggestion": "Add funds to your account or choose a lower-priced asset",
    "support_url": "https://docs.gitstable.com/errors/insufficient-funds"
  }
}

Rate Limits & Best Practices

📊 Rate Limit Details

Operation Type Standard Bot Enterprise Bot Reset Period
Asset Search 500/min 5,000/min 1 minute
Single Purchase 50/min 500/min 1 minute
Bulk Purchase 10/min 100/min 1 minute
Inference API 1,000/min 10,000/min 1 minute
License Management 200/min 2,000/min 1 minute

🔧 Best Practices

  • Implement exponential backoff: When rate limited, wait progressively longer between retries
  • Cache asset metadata: Avoid repeated searches for the same assets
  • Use bulk operations: Purchase multiple assets in single transactions when possible
  • Monitor rate limit headers: Track remaining requests in response headers
  • Implement circuit breakers: Temporarily halt requests when error rates are high

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 856
X-RateLimit-Reset: 1692276000
X-RateLimit-Retry-After: 45