feat: add marketplace metrics, privacy features, and service registry endpoints
- Add Prometheus metrics for marketplace API throughput and error rates with new dashboard panels - Implement confidential transaction models with encryption support and access control - Add key management system with registration, rotation, and audit logging - Create services and registry routers for service discovery and management - Integrate ZK proof generation for privacy-preserving receipts - Add metrics instru
This commit is contained in:
oib
111
docs/developer/api/api/coordinator/authentication.md
Normal file
111
docs/developer/api/api/coordinator/authentication.md
Normal file
@ -0,0 +1,111 @@
|
||||
---
|
||||
title: API Authentication
|
||||
description: Understanding authentication for the Coordinator API
|
||||
---
|
||||
|
||||
# API Authentication
|
||||
|
||||
All Coordinator API endpoints require authentication using API keys.
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. Sign up at [AITBC Dashboard](https://dashboard.aitbc.io)
|
||||
2. Generate an API key
|
||||
3. Include the key in your requests
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
### HTTP Header (Recommended)
|
||||
```http
|
||||
X-API-Key: your_api_key_here
|
||||
```
|
||||
|
||||
### Query Parameter
|
||||
```http
|
||||
GET /v1/jobs?api_key=your_api_key_here
|
||||
```
|
||||
|
||||
## Example Requests
|
||||
|
||||
### cURL
|
||||
```bash
|
||||
curl -X GET https://api.aitbc.io/v1/jobs \
|
||||
-H "X-API-Key: your_api_key_here"
|
||||
```
|
||||
|
||||
### Python
|
||||
```python
|
||||
import requests
|
||||
|
||||
headers = {
|
||||
"X-API-Key": "your_api_key_here"
|
||||
}
|
||||
|
||||
response = requests.get(
|
||||
"https://api.aitbc.io/v1/jobs",
|
||||
headers=headers
|
||||
)
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
```javascript
|
||||
const headers = {
|
||||
"X-API-Key": "your_api_key_here"
|
||||
};
|
||||
|
||||
fetch("https://api.aitbc.io/v1/jobs", {
|
||||
headers: headers
|
||||
})
|
||||
.then(response => response.json())
|
||||
.then(data => console.log(data));
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
- Never expose API keys in client-side code
|
||||
- Use environment variables in production
|
||||
- Rotate keys regularly
|
||||
- Monitor API usage
|
||||
- Use HTTPS for all requests
|
||||
|
||||
## Rate Limits
|
||||
|
||||
API requests are rate-limited based on your plan:
|
||||
- Free: 60 requests/minute
|
||||
- Pro: 600 requests/minute
|
||||
- Enterprise: 6000 requests/minute
|
||||
|
||||
Rate limit headers are included in responses:
|
||||
```http
|
||||
X-RateLimit-Limit: 60
|
||||
X-RateLimit-Remaining: 59
|
||||
X-RateLimit-Reset: 1640995200
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "INVALID_API_KEY",
|
||||
"message": "The provided API key is invalid"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Management
|
||||
|
||||
### View Your Keys
|
||||
Visit the [Dashboard](https://dashboard.aitbc.io/api-keys)
|
||||
|
||||
### Revoke a Key
|
||||
```bash
|
||||
curl -X DELETE https://api.aitbc.io/v1/api-keys/{key_id} \
|
||||
-H "X-API-Key: your_master_key"
|
||||
```
|
||||
|
||||
### Regenerate a Key
|
||||
```bash
|
||||
curl -X POST https://api.aitbc.io/v1/api-keys/{key_id}/regenerate \
|
||||
-H "X-API-Key: your_master_key"
|
||||
```
|
||||
575
docs/developer/api/api/coordinator/endpoints.md
Normal file
575
docs/developer/api/api/coordinator/endpoints.md
Normal file
@ -0,0 +1,575 @@
|
||||
---
|
||||
title: API Endpoints
|
||||
description: Complete list of Coordinator API endpoints
|
||||
---
|
||||
|
||||
# API Endpoints
|
||||
|
||||
## Jobs
|
||||
|
||||
### Create Job
|
||||
```http
|
||||
POST /v1/jobs
|
||||
```
|
||||
|
||||
Create a new AI job.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "image-classification",
|
||||
"type": "ai-inference",
|
||||
"model": {
|
||||
"type": "python",
|
||||
"entrypoint": "model.py",
|
||||
"requirements": ["numpy", "torch"]
|
||||
},
|
||||
"input": {
|
||||
"type": "image",
|
||||
"format": "jpeg"
|
||||
},
|
||||
"output": {
|
||||
"type": "json"
|
||||
},
|
||||
"resources": {
|
||||
"cpu": "1000m",
|
||||
"memory": "2Gi",
|
||||
"gpu": "1"
|
||||
},
|
||||
"pricing": {
|
||||
"max_cost": "0.10"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"job_id": "job_1234567890",
|
||||
"status": "submitted",
|
||||
"created_at": "2024-01-01T12:00:00Z",
|
||||
"estimated_completion": "2024-01-01T12:05:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Job Status
|
||||
```http
|
||||
GET /v1/jobs/{job_id}
|
||||
```
|
||||
|
||||
Retrieve the current status of a job.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"job_id": "job_1234567890",
|
||||
"status": "running",
|
||||
"progress": 75,
|
||||
"created_at": "2024-01-01T12:00:00Z",
|
||||
"started_at": "2024-01-01T12:01:00Z",
|
||||
"estimated_completion": "2024-01-01T12:05:00Z",
|
||||
"miner_id": "miner_1234567890"
|
||||
}
|
||||
```
|
||||
|
||||
### List Jobs
|
||||
```http
|
||||
GET /v1/jobs
|
||||
```
|
||||
|
||||
List all jobs with optional filtering.
|
||||
|
||||
**Query Parameters:**
|
||||
- `status` (string): Filter by status (submitted, running, completed, failed)
|
||||
- `type` (string): Filter by job type
|
||||
- `limit` (integer): Maximum number of jobs to return (default: 50)
|
||||
- `offset` (integer): Number of jobs to skip (default: 0)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"jobs": [
|
||||
{
|
||||
"job_id": "job_1234567890",
|
||||
"status": "completed",
|
||||
"type": "ai-inference",
|
||||
"created_at": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"limit": 50,
|
||||
"offset": 0
|
||||
}
|
||||
```
|
||||
|
||||
### Cancel Job
|
||||
```http
|
||||
DELETE /v1/jobs/{job_id}
|
||||
```
|
||||
|
||||
Cancel a running or submitted job.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"job_id": "job_1234567890",
|
||||
"status": "cancelled",
|
||||
"cancelled_at": "2024-01-01T12:03:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Job Results
|
||||
```http
|
||||
GET /v1/jobs/{job_id}/results
|
||||
```
|
||||
|
||||
Retrieve the results of a completed job.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"job_id": "job_1234567890",
|
||||
"status": "completed",
|
||||
"results": {
|
||||
"prediction": "cat",
|
||||
"confidence": 0.95,
|
||||
"processing_time": 1.23
|
||||
},
|
||||
"completed_at": "2024-01-01T12:04:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Marketplace
|
||||
|
||||
### Create Offer
|
||||
```http
|
||||
POST /v1/marketplace/offers
|
||||
```
|
||||
|
||||
Create a new marketplace offer for job execution.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"job_type": "image-classification",
|
||||
"price": "0.001",
|
||||
"max_jobs": 10,
|
||||
"requirements": {
|
||||
"min_gpu_memory": "4Gi",
|
||||
"min_cpu": "2000m"
|
||||
},
|
||||
"duration": 3600
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"offer_id": "offer_1234567890",
|
||||
"miner_id": "miner_1234567890",
|
||||
"status": "active",
|
||||
"created_at": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### List Offers
|
||||
```http
|
||||
GET /v1/marketplace/offers
|
||||
```
|
||||
|
||||
List all active marketplace offers.
|
||||
|
||||
**Query Parameters:**
|
||||
- `job_type` (string): Filter by job type
|
||||
- `max_price` (string): Maximum price filter
|
||||
- `limit` (integer): Maximum number of offers (default: 50)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"offers": [
|
||||
{
|
||||
"offer_id": "offer_1234567890",
|
||||
"miner_id": "miner_1234567890",
|
||||
"job_type": "image-classification",
|
||||
"price": "0.001",
|
||||
"reputation": 4.8
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Accept Offer
|
||||
```http
|
||||
POST /v1/marketplace/offers/{offer_id}/accept
|
||||
```
|
||||
|
||||
Accept a marketplace offer for job execution.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"job_id": "job_1234567890",
|
||||
"bid_price": "0.001"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"transaction_id": "tx_1234567890",
|
||||
"status": "pending",
|
||||
"created_at": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Receipts
|
||||
|
||||
### Get Receipt
|
||||
```http
|
||||
GET /v1/receipts/{job_id}
|
||||
```
|
||||
|
||||
Retrieve the receipt for a completed job.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"receipt_id": "receipt_1234567890",
|
||||
"job_id": "job_1234567890",
|
||||
"miner_id": "miner_1234567890",
|
||||
"signature": {
|
||||
"sig": "base64_signature",
|
||||
"public_key": "base64_public_key"
|
||||
},
|
||||
"attestations": [
|
||||
{
|
||||
"type": "completion",
|
||||
"timestamp": "2024-01-01T12:04:00Z",
|
||||
"signature": "base64_attestation"
|
||||
}
|
||||
],
|
||||
"created_at": "2024-01-01T12:04:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Verify Receipt
|
||||
```http
|
||||
POST /v1/receipts/verify
|
||||
```
|
||||
|
||||
Verify the authenticity of a receipt.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"receipt": {
|
||||
"receipt_id": "receipt_1234567890",
|
||||
"signature": {
|
||||
"sig": "base64_signature",
|
||||
"public_key": "base64_public_key"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"valid": true,
|
||||
"miner_signature_valid": true,
|
||||
"coordinator_attestations": 2,
|
||||
"verified_at": "2024-01-01T12:05:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Analytics
|
||||
|
||||
### Get Marketplace Stats
|
||||
```http
|
||||
GET /v1/marketplace/stats
|
||||
```
|
||||
|
||||
Retrieve marketplace statistics.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total_jobs": 10000,
|
||||
"active_jobs": 150,
|
||||
"completed_jobs": 9800,
|
||||
"failed_jobs": 50,
|
||||
"average_completion_time": 120.5,
|
||||
"total_volume": "1500.50",
|
||||
"active_miners": 500
|
||||
}
|
||||
```
|
||||
|
||||
### Get Miner Stats
|
||||
```http
|
||||
GET /v1/miners/{miner_id}/stats
|
||||
```
|
||||
|
||||
Retrieve statistics for a specific miner.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"miner_id": "miner_1234567890",
|
||||
"reputation": 4.8,
|
||||
"total_jobs": 500,
|
||||
"success_rate": 0.98,
|
||||
"average_completion_time": 115.2,
|
||||
"total_earned": "125.50",
|
||||
"active_since": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Health
|
||||
|
||||
### Health Check
|
||||
```http
|
||||
GET /v1/health
|
||||
```
|
||||
|
||||
Check the health status of the coordinator service.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "1.0.0",
|
||||
"environment": "production",
|
||||
"timestamp": "2024-01-01T12:00:00Z",
|
||||
"services": {
|
||||
"database": "healthy",
|
||||
"blockchain": "healthy",
|
||||
"marketplace": "healthy"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## WebSocket API
|
||||
|
||||
### Real-time Updates
|
||||
```
|
||||
WSS /ws
|
||||
```
|
||||
|
||||
Connect to receive real-time updates about jobs and marketplace events.
|
||||
|
||||
**Message Types:**
|
||||
- `job_update`: Job status changes
|
||||
- `marketplace_update`: New offers or transactions
|
||||
- `receipt_created`: New receipts generated
|
||||
|
||||
**Example Message:**
|
||||
```json
|
||||
{
|
||||
"type": "job_update",
|
||||
"data": {
|
||||
"job_id": "job_1234567890",
|
||||
"status": "completed",
|
||||
"timestamp": "2024-01-01T12:04:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Description | HTTP Status |
|
||||
|------|-------------|-------------|
|
||||
| `INVALID_JOB_TYPE` | Unsupported job type | 400 |
|
||||
| `INSUFFICIENT_BALANCE` | Not enough funds in wallet | 402 |
|
||||
| `JOB_NOT_FOUND` | Job does not exist | 404 |
|
||||
| `JOB_ALREADY_COMPLETED` | Cannot modify completed job | 409 |
|
||||
| `OFFER_NOT_AVAILABLE` | Offer is no longer available | 410 |
|
||||
| `RATE_LIMIT_EXCEEDED` | Too many requests | 429 |
|
||||
| `INTERNAL_ERROR` | Server error | 500 |
|
||||
|
||||
## SDK Examples
|
||||
|
||||
### Python
|
||||
```python
|
||||
from aitbc import AITBCClient
|
||||
|
||||
client = AITBCClient(api_key="your_key")
|
||||
|
||||
# Create a job
|
||||
job = client.jobs.create({
|
||||
"name": "my-job",
|
||||
"type": "ai-inference",
|
||||
...
|
||||
})
|
||||
|
||||
# Get results
|
||||
results = client.jobs.get_results(job["job_id"])
|
||||
```
|
||||
|
||||
### JavaScript
|
||||
```javascript
|
||||
import { AITBCClient } from '@aitbc/client';
|
||||
|
||||
const client = new AITBCClient({ apiKey: 'your_key' });
|
||||
|
||||
// Create a job
|
||||
const job = await client.jobs.create({
|
||||
name: 'my-job',
|
||||
type: 'ai-inference',
|
||||
...
|
||||
});
|
||||
|
||||
// Get results
|
||||
const results = await client.jobs.getResults(job.jobId);
|
||||
```
|
||||
|
||||
## Services
|
||||
|
||||
### Whisper Transcription
|
||||
```http
|
||||
POST /v1/services/whisper/transcribe
|
||||
```
|
||||
|
||||
Transcribe audio file using Whisper.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"audio_url": "https://example.com/audio.mp3",
|
||||
"model": "base",
|
||||
"language": "en",
|
||||
"task": "transcribe"
|
||||
}
|
||||
```
|
||||
|
||||
### Stable Diffusion Generation
|
||||
```http
|
||||
POST /v1/services/stable-diffusion/generate
|
||||
```
|
||||
|
||||
Generate images from text prompts.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"prompt": "A beautiful sunset over mountains",
|
||||
"model": "stable-diffusion-1.5",
|
||||
"size": "1024x1024",
|
||||
"num_images": 1,
|
||||
"steps": 20
|
||||
}
|
||||
```
|
||||
|
||||
### LLM Inference
|
||||
```http
|
||||
POST /v1/services/llm/inference
|
||||
```
|
||||
|
||||
Run inference on language models.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"model": "llama-7b",
|
||||
"prompt": "Explain quantum computing",
|
||||
"max_tokens": 256,
|
||||
"temperature": 0.7
|
||||
}
|
||||
```
|
||||
|
||||
### Video Transcoding
|
||||
```http
|
||||
POST /v1/services/ffmpeg/transcode
|
||||
```
|
||||
|
||||
Transcode video files.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"input_url": "https://example.com/video.mp4",
|
||||
"output_format": "mp4",
|
||||
"codec": "h264",
|
||||
"resolution": "1920x1080"
|
||||
}
|
||||
```
|
||||
|
||||
### 3D Rendering
|
||||
```http
|
||||
POST /v1/services/blender/render
|
||||
```
|
||||
|
||||
Render 3D scenes with Blender.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"blend_file_url": "https://example.com/scene.blend",
|
||||
"engine": "cycles",
|
||||
"resolution_x": 1920,
|
||||
"resolution_y": 1080,
|
||||
"samples": 128
|
||||
}
|
||||
```
|
||||
|
||||
## Service Registry
|
||||
|
||||
### List All Services
|
||||
```http
|
||||
GET /v1/registry/services
|
||||
```
|
||||
|
||||
List all available GPU services with optional filtering.
|
||||
|
||||
**Query Parameters:**
|
||||
- `category` (optional): Filter by service category
|
||||
- `search` (optional): Search by name, description, or tags
|
||||
|
||||
### Get Service Definition
|
||||
```http
|
||||
GET /v1/registry/services/{service_id}
|
||||
```
|
||||
|
||||
Get detailed definition for a specific service.
|
||||
|
||||
### Get Service Schema
|
||||
```http
|
||||
GET /v1/registry/services/{service_id}/schema
|
||||
```
|
||||
|
||||
Get JSON schema for service input parameters.
|
||||
|
||||
### Get Service Requirements
|
||||
```http
|
||||
GET /v1/registry/services/{service_id}/requirements
|
||||
```
|
||||
|
||||
Get hardware requirements for a service.
|
||||
|
||||
### Validate Service Request
|
||||
```http
|
||||
POST /v1/registry/services/validate
|
||||
```
|
||||
|
||||
Validate a service request against the service schema.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"service_id": "llm_inference",
|
||||
"request_data": {
|
||||
"model": "llama-7b",
|
||||
"prompt": "Hello world",
|
||||
"max_tokens": 256
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"valid": true,
|
||||
"errors": [],
|
||||
"warnings": []
|
||||
}
|
||||
```
|
||||
79
docs/developer/api/api/coordinator/openapi.md
Normal file
79
docs/developer/api/api/coordinator/openapi.md
Normal file
@ -0,0 +1,79 @@
|
||||
---
|
||||
title: OpenAPI Specification
|
||||
description: Complete OpenAPI specification for the Coordinator API
|
||||
---
|
||||
|
||||
# OpenAPI Specification
|
||||
|
||||
The complete OpenAPI 3.0 specification for the AITBC Coordinator API is available below.
|
||||
|
||||
## Interactive Documentation
|
||||
|
||||
- [Swagger UI](https://api.aitbc.io/docs) - Interactive API explorer
|
||||
- [ReDoc](https://api.aitbc.io/redoc) - Alternative documentation view
|
||||
|
||||
## Download Specification
|
||||
|
||||
- [JSON Format](openapi.json) - Raw OpenAPI JSON
|
||||
- [YAML Format](openapi.yaml) - OpenAPI YAML format
|
||||
|
||||
## Key Endpoints
|
||||
|
||||
### Jobs
|
||||
- `POST /v1/jobs` - Create a new job
|
||||
- `GET /v1/jobs/{job_id}` - Get job details
|
||||
- `GET /v1/jobs` - List jobs
|
||||
- `DELETE /v1/jobs/{job_id}` - Cancel job
|
||||
- `GET /v1/jobs/{job_id}/results` - Get job results
|
||||
|
||||
### Marketplace
|
||||
- `POST /v1/marketplace/offers` - Create offer
|
||||
- `GET /v1/marketplace/offers` - List offers
|
||||
- `POST /v1/marketplace/offers/{offer_id}/accept` - Accept offer
|
||||
|
||||
### Receipts
|
||||
- `GET /v1/receipts/{job_id}` - Get receipt
|
||||
- `POST /v1/receipts/verify` - Verify receipt
|
||||
|
||||
### Analytics
|
||||
- `GET /v1/marketplace/stats` - Get marketplace statistics
|
||||
- `GET /v1/miners/{miner_id}/stats` - Get miner statistics
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication via the `X-API-Key` header.
|
||||
|
||||
## Rate Limits
|
||||
|
||||
API requests are rate-limited based on your subscription plan.
|
||||
|
||||
## WebSocket API
|
||||
|
||||
Real-time updates available at:
|
||||
- WebSocket: `wss://api.aitbc.io/ws`
|
||||
- Message types: job_update, marketplace_update, receipt_created
|
||||
|
||||
## Code Generation
|
||||
|
||||
Use the OpenAPI spec to generate client libraries:
|
||||
|
||||
```bash
|
||||
# OpenAPI Generator
|
||||
openapi-generator-cli generate -i openapi.json -g python -o ./client/
|
||||
|
||||
# Or use the online generator at https://openapi-generator.tech/
|
||||
```
|
||||
|
||||
## SDK Integration
|
||||
|
||||
The OpenAPI spec is integrated into our official SDKs:
|
||||
- [Python SDK](../../developer-guide/sdks/python.md)
|
||||
- [JavaScript SDK](../../developer-guide/sdks/javascript.md)
|
||||
|
||||
## Support
|
||||
|
||||
For API support:
|
||||
- 📖 [API Documentation](endpoints.md)
|
||||
- 🐛 [Report Issues](https://github.com/aitbc/issues)
|
||||
- 💬 [Discord](https://discord.gg/aitbc)
|
||||
- 📧 [api-support@aitbc.io](mailto:api-support@aitbc.io)
|
||||
140
docs/developer/api/api/coordinator/overview.md
Normal file
140
docs/developer/api/api/coordinator/overview.md
Normal file
@ -0,0 +1,140 @@
|
||||
---
|
||||
title: Coordinator API Overview
|
||||
description: Introduction to the AITBC Coordinator API
|
||||
---
|
||||
|
||||
# Coordinator API Overview
|
||||
|
||||
The Coordinator API is the central service of the AITBC platform, responsible for job management, marketplace operations, and coordination between various components.
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
Production: https://api.aitbc.io
|
||||
Staging: https://staging-api.aitbc.io
|
||||
Development: http://localhost:8011
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
All API endpoints require authentication using an API key. Include the API key in the request header:
|
||||
|
||||
```http
|
||||
X-API-Key: your_api_key_here
|
||||
```
|
||||
|
||||
Get your API key from the [AITBC Dashboard](https://dashboard.aitbc.io).
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Jobs
|
||||
Jobs are the primary unit of work in AITBC. They represent AI computations that need to be executed.
|
||||
|
||||
```json
|
||||
{
|
||||
"job_id": "job_1234567890",
|
||||
"type": "ai-inference",
|
||||
"status": "running",
|
||||
"created_at": "2024-01-01T12:00:00Z",
|
||||
"estimated_completion": "2024-01-01T12:05:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Marketplace
|
||||
The marketplace connects job creators with miners who can execute the jobs.
|
||||
|
||||
```json
|
||||
{
|
||||
"offer_id": "offer_1234567890",
|
||||
"job_type": "image-classification",
|
||||
"price": "0.001",
|
||||
"miner_id": "miner_1234567890"
|
||||
}
|
||||
```
|
||||
|
||||
### Receipts
|
||||
Receipts provide cryptographic proof of job execution and results.
|
||||
|
||||
```json
|
||||
{
|
||||
"receipt_id": "receipt_1234567890",
|
||||
"job_id": "job_1234567890",
|
||||
"signature": {
|
||||
"sig": "base64_signature",
|
||||
"public_key": "base64_public_key"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limits
|
||||
|
||||
API requests are rate-limited to ensure fair usage:
|
||||
|
||||
| Plan | Requests per minute | Burst |
|
||||
|------|---------------------|-------|
|
||||
| Free | 60 | 10 |
|
||||
| Pro | 600 | 100 |
|
||||
| Enterprise | 6000 | 1000 |
|
||||
|
||||
## Error Handling
|
||||
|
||||
The API uses standard HTTP status codes and returns detailed error messages:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "INVALID_API_KEY",
|
||||
"message": "The provided API key is invalid",
|
||||
"details": {
|
||||
"request_id": "req_1234567890"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
- `400 Bad Request` - Invalid request parameters
|
||||
- `401 Unauthorized` - Invalid or missing API key
|
||||
- `403 Forbidden` - Insufficient permissions
|
||||
- `404 Not Found` - Resource not found
|
||||
- `429 Too Many Requests` - Rate limit exceeded
|
||||
- `500 Internal Server Error` - Server error
|
||||
|
||||
## SDK Support
|
||||
|
||||
Official SDKs are available for:
|
||||
- [Python](../../developer-guide/sdks/python.md)
|
||||
- [JavaScript/TypeScript](../../developer-guide/sdks/javascript.md)
|
||||
|
||||
## WebSocket API
|
||||
|
||||
Real-time updates are available through WebSocket connections:
|
||||
|
||||
```javascript
|
||||
const ws = new WebSocket('wss://api.aitbc.io/ws');
|
||||
|
||||
ws.onmessage = (event) => {
|
||||
const data = JSON.parse(event.data);
|
||||
console.log('Job update:', data);
|
||||
};
|
||||
```
|
||||
|
||||
## OpenAPI Specification
|
||||
|
||||
The complete OpenAPI 3.0 specification is available:
|
||||
- [View in Swagger UI](https://api.aitbc.io/docs)
|
||||
- [Download JSON](openapi.md)
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. [Get an API key](https://dashboard.aitbc.io/api-keys)
|
||||
2. [Review authentication](authentication.md)
|
||||
3. [Explore endpoints](endpoints.md)
|
||||
4. [Check examples](../../developer-guide/examples.md)
|
||||
|
||||
## Support
|
||||
|
||||
- 📖 [Documentation](../../)
|
||||
- 💬 [Discord](https://discord.gg/aitbc)
|
||||
- 🐛 [Report Issues](https://github.com/aitbc/issues)
|
||||
- 📧 [api-support@aitbc.io](mailto:api-support@aitbc.io)
|
||||
Reference in New Issue
Block a user