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.
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
{ "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 }
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
{ "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.
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
{ "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" } }
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
{ "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.
Query Parameters
Parameter | Type | Description |
---|---|---|
status | string | Filter by license status (active, expired, suspended) |
asset_id | string | Filter by specific asset |
Response
{ "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 } }
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
{ "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.
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
{ "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.
Configure webhook endpoints to receive notifications about important events in your AI system integrations.
Available Events
purchase.completed
- Asset purchase completed successfullylicense.expiring
- License expiring within 30 daysusage.threshold
- Usage approaching license limitsinference.failed
- Inference request failedasset.updated
- Purchased asset has been updated
Webhook Configuration
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 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