oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity
Files
0cbd2b507c49ccde3959e8435dca66c5a039fa74
aitbc/docs/reference/specs/api-reference.md
oib 329b3beeba ``` 
feat: add SQLModel relationships, fix ZK verifier circuit integration, and complete Stage 19-20 documentation

- Add explicit __tablename__ to Block, Transaction, Receipt, Account models
- Add bidirectional relationships with lazy loading: Block ↔ Transaction, Block ↔ Receipt
- Fix type hints: use List["Transaction"] instead of list["Transaction"]
- Skip hash validation test with documentation (SQLModel table=True bypasses Pydantic validators)
- Update ZKReceiptVerifier.sol to match receipt_simple circuit (
2026-01-24 18:34:37 +01:00

517 lines
11 KiB
Markdown
Raw Blame History

# AITBC API Reference (OpenAPI)
This document provides the complete API reference for the AITBC Coordinator API.
## Base URL
```
Production: https://aitbc.bubuit.net/api
Local: http://127.0.0.1:8001
```
## Authentication
Most endpoints require an API key passed in the header:
```
X-Api-Key: your-api-key
```
## OpenAPI Specification
```yaml
openapi: 3.0.3
info:
title: AITBC Coordinator API
version: 1.0.0
description: API for submitting AI compute jobs and managing the AITBC network
servers:
- url: https://aitbc.bubuit.net/api
description: Production
- url: http://127.0.0.1:8001
description: Local development
paths:
/health:
get:
summary: Health check
tags: [System]
responses:
'200':
description: Service is healthy
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ok
version:
type: string
example: 1.0.0
/v1/jobs:
post:
summary: Submit a new job
tags: [Jobs]
security:
- ApiKey: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobRequest'
responses:
'201':
description: Job created
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
summary: List jobs
tags: [Jobs]
parameters:
- name: status
in: query
schema:
type: string
enum: [pending, running, completed, failed, cancelled]
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
- name: offset
in: query
schema:
type: integer
default: 0
responses:
'200':
description: List of jobs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Job'
/v1/jobs/{job_id}:
get:
summary: Get job details
tags: [Jobs]
parameters:
- name: job_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Job details
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'404':
$ref: '#/components/responses/NotFound'
/v1/jobs/{job_id}/cancel:
post:
summary: Cancel a job
tags: [Jobs]
parameters:
- name: job_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Job cancelled
'404':
$ref: '#/components/responses/NotFound'
'409':
description: Job cannot be cancelled (already completed)
/v1/jobs/available:
get:
summary: Get available jobs for miners
tags: [Miners]
parameters:
- name: miner_id
in: query
required: true
schema:
type: string
responses:
'200':
description: Available job or null
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
/v1/jobs/{job_id}/claim:
post:
summary: Claim a job for processing
tags: [Miners]
parameters:
- name: job_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
miner_id:
type: string
required:
- miner_id
responses:
'200':
description: Job claimed
'409':
description: Job already claimed
/v1/jobs/{job_id}/complete:
post:
summary: Submit job result
tags: [Miners]
parameters:
- name: job_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobResult'
responses:
'200':
description: Job completed
content:
application/json:
schema:
$ref: '#/components/schemas/Receipt'
/v1/miners/register:
post:
summary: Register a miner
tags: [Miners]
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MinerRegistration'
responses:
'201':
description: Miner registered
'400':
$ref: '#/components/responses/BadRequest'
/v1/receipts:
get:
summary: List receipts
tags: [Receipts]
parameters:
- name: client
in: query
schema:
type: string
- name: provider
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: List of receipts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Receipt'
/v1/receipts/{receipt_id}:
get:
summary: Get receipt details
tags: [Receipts]
parameters:
- name: receipt_id
in: path
required: true
schema:
type: string
responses:
'200':
description: Receipt details
content:
application/json:
schema:
$ref: '#/components/schemas/Receipt'
'404':
$ref: '#/components/responses/NotFound'
/explorer/blocks:
get:
summary: Get recent blocks
tags: [Explorer]
parameters:
- name: limit
in: query
schema:
type: integer
default: 10
responses:
'200':
description: List of blocks
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Block'
/explorer/transactions:
get:
summary: Get recent transactions
tags: [Explorer]
responses:
'200':
description: List of transactions
/explorer/receipts:
get:
summary: Get recent receipts
tags: [Explorer]
responses:
'200':
description: List of receipts
/explorer/stats:
get:
summary: Get network statistics
tags: [Explorer]
responses:
'200':
description: Network stats
content:
application/json:
schema:
$ref: '#/components/schemas/NetworkStats'
components:
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-Api-Key
schemas:
JobRequest:
type: object
properties:
prompt:
type: string
description: Input prompt
model:
type: string
default: llama3.2
params:
type: object
properties:
max_tokens:
type: integer
default: 256
temperature:
type: number
default: 0.7
top_p:
type: number
default: 0.9
required:
- prompt
Job:
type: object
properties:
job_id:
type: string
status:
type: string
enum: [pending, running, completed, failed, cancelled]
prompt:
type: string
model:
type: string
result:
type: string
miner_id:
type: string
created_at:
type: string
format: date-time
started_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
JobResult:
type: object
properties:
miner_id:
type: string
result:
type: string
completed_at:
type: string
format: date-time
required:
- miner_id
- result
Receipt:
type: object
properties:
receipt_id:
type: string
job_id:
type: string
provider:
type: string
client:
type: string
units:
type: number
unit_type:
type: string
price:
type: number
model:
type: string
started_at:
type: integer
completed_at:
type: integer
signature:
$ref: '#/components/schemas/Signature'
Signature:
type: object
properties:
alg:
type: string
key_id:
type: string
sig:
type: string
MinerRegistration:
type: object
properties:
miner_id:
type: string
capabilities:
type: array
items:
type: string
gpu_info:
type: object
properties:
name:
type: string
memory:
type: string
required:
- miner_id
- capabilities
Block:
type: object
properties:
height:
type: integer
hash:
type: string
timestamp:
type: string
format: date-time
transactions:
type: integer
NetworkStats:
type: object
properties:
total_jobs:
type: integer
active_miners:
type: integer
total_receipts:
type: integer
block_height:
type: integer
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Error:
type: object
properties:
detail:
type: string
error_code:
type: string
```
## Interactive Documentation
Access the interactive API documentation at:
- **Swagger UI**: https://aitbc.bubuit.net/api/docs
- **ReDoc**: https://aitbc.bubuit.net/api/redoc
Reference in New Issue View Git Blame Copy Permalink