aitbc/docs/api/examples/curl-examples.md

cURL Examples

This document provides comprehensive cURL examples for interacting with the AITBC APIs.

Common Headers

# Set API key header
export API_KEY="your-api-key"
export BASE_URL="http://localhost:8011"

# Common curl command pattern
curl -H "X-Api-Key: $API_KEY" $BASE_URL/v1/endpoint

Coordinator API Examples

Job Submission

Simple Job Submission

curl -X POST $BASE_URL/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "payload": {
      "model": "llama2",
      "prompt": "Hello, world!"
    },
    "ttl_seconds": 900
  }'

Job with Constraints

curl -X POST $BASE_URL/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "payload": {
      "model": "llama2",
      "prompt": "Hello, world!"
    },
    "constraints": {
      "min_gpu_memory": 8,
      "gpu_type": "nvidia-rtx-3090"
    },
    "ttl_seconds": 900
  }'

Job with Payment

curl -X POST $BASE_URL/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{
    "payload": {
      "model": "llama2",
      "prompt": "Hello, world!"
    },
    "payment_amount": 100.0,
    "payment_currency": "AITBC",
    "ttl_seconds": 900
  }'

Job Status

Get Job Status

curl -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}

Poll for Completion

#!/bin/bash

JOB_ID="your-job-id"

while true; do
  STATUS=$(curl -s -H "X-Api-Key: $API_KEY" \
    $BASE_URL/v1/jobs/$JOB_ID | jq -r '.state')
  
  echo "State: $STATUS"
  
  if [[ "$STATUS" =~ ^(COMPLETED|FAILED|CANCELLED|EXPIRED)$ ]]; then
    break
  fi
  
  sleep 5
done

Job Results

Get Job Result

curl -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}/result

Get Receipts

# Get latest receipt
curl -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}/receipt

# Get all receipts
curl -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}/receipts

Job Cancellation

curl -X POST \
  -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}/cancel

Payment Operations

Get Payment Status

curl -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}/payment

Blockchain API Examples

Block Operations

Get Head Block

export BLOCKCHAIN_URL="http://localhost:8080"

curl $BLOCKCHAIN_URL/v1/blocks/head

Get Block by Height

curl $BLOCKCHAIN_URL/v1/blocks/12345

Get Block Range

curl "$BLOCKCHAIN_URL/v1/blocks?from=12340&to=12350"

Transaction Operations

Get Transaction

curl $BLOCKCHAIN_URL/v1/transactions/{tx_hash}

Submit Transaction

curl -X POST $BLOCKCHAIN_URL/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0x...",
    "to": "0x...",
    "value": 1000,
    "gas": 21000,
    "data": "0x...",
    "signature": "0x..."
  }'

Network Status

Get Network Info

curl $BLOCKCHAIN_URL/v1/network

Get Peers

curl $BLOCKCHAIN_URL/v1/network/peers

Smart Contract Operations

Call Contract (Read-only)

curl -X POST $BLOCKCHAIN_URL/v1/contracts/{address}/call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "balanceOf",
    "args": ["0x..."]
  }'

Send Transaction to Contract (State-changing)

curl -X POST $BLOCKCHAIN_URL/v1/contracts/{address}/transact \
  -H "Content-Type: application/json" \
  -d '{
    "method": "transfer",
    "args": ["0x...", 1000],
    "gas": 100000,
    "value": 0
  }'

Advanced cURL Examples

Using jq for JSON Processing

# Extract job ID from response
JOB_ID=$(curl -s -X POST $BASE_URL/v1/jobs \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  -d '{"payload": {"model": "llama2", "prompt": "Hello"}, "ttl_seconds": 900}' \
  | jq -r '.job_id')

echo "Job ID: $JOB_ID"

Pretty Print JSON Output

curl -s -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id} | jq '.'

Extract Specific Fields

# Get job state only
curl -s -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id} | jq -r '.state'

# Get multiple fields
curl -s -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id} | jq '{state: .state, assigned_miner_id: .assigned_miner_id}'

Batch Operations

# Submit multiple jobs
for prompt in "Hello" "World" "Test"; do
  curl -X POST $BASE_URL/v1/jobs \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: $API_KEY" \
    -d "{\"payload\": {\"model\": \"llama2\", \"prompt\": \"$prompt\"}, \"ttl_seconds\": 900}" &
done

wait

Error Handling

# Check HTTP status code
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id})

if [ $HTTP_CODE -eq 200 ]; then
  echo "Success"
else
  echo "Failed with status code: $HTTP_CODE"
fi

Rate Limiting

# Add delay between requests to respect rate limits
for i in {1..10}; do
  curl -H "X-Api-Key: $API_KEY" \
    $BASE_URL/v1/jobs/{job_id}
  sleep 1  # 1 second delay
done

Retry Logic

#!/bin/bash

MAX_RETRIES=3
RETRY_DELAY=5

for i in $(seq 1 $MAX_RETRIES); do
  RESPONSE=$(curl -s -w "\n%{http_code}" \
    -H "X-Api-Key: $API_KEY" \
    $BASE_URL/v1/jobs/{job_id})
  
  HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
  BODY=$(echo "$RESPONSE" | head -n-1)
  
  if [ $HTTP_CODE -eq 200 ]; then
    echo "$BODY"
    exit 0
  fi
  
  echo "Attempt $i failed with status $HTTP_CODE"
  sleep $RETRY_DELAY
done

echo "Max retries exceeded"
exit 1

File Upload

# Upload file as job payload
curl -X POST $BASE_URL/v1/jobs \
  -H "Content-Type: multipart/form-data" \
  -H "X-Api-Key: $API_KEY" \
  -F "payload=@input.json" \
  -F "ttl_seconds=900"

Download Results

# Download job result to file
curl -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}/result \
  -o result.json

WebSocket Testing

# Test WebSocket connection (requires websocat)
websocat ws://localhost:8011/v1/jobs/{job_id}/ws

Configuration Files

.curlrc Configuration

# ~/.curlrc
header = "X-Api-Key: your-api-key"
header = "Content-Type: application/json"
silent = false
show-error = true

Environment Variables

# ~/.bashrc or ~/.zshrc
export AITBC_API_KEY="your-api-key"
export AITBC_BASE_URL="http://localhost:8011"
export AITBC_BLOCKCHAIN_URL="http://localhost:8080"

Shell Functions

# Add to ~/.bashrc or ~/.zshrc

# Submit job function
aitbc-submit() {
  curl -X POST $AITBC_BASE_URL/v1/jobs \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: $AITBC_API_KEY" \
    -d "$1"
}

# Get job function
aitbc-job() {
  curl -H "X-Api-Key: $AITBC_API_KEY" \
    $AITBC_BASE_URL/v1/jobs/$1
}

# Get result function
aitbc-result() {
  curl -H "X-Api-Key: $AITBC_API_KEY" \
    $AITBC_BASE_URL/v1/jobs/$1/result
}

Debugging

Verbose Output

curl -v -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}

Include Headers in Response

curl -i -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}

Timing Information

curl -w "@curl-format.txt" \
  -H "X-Api-Key: $API_KEY" \
  $BASE_URL/v1/jobs/{job_id}

curl-format.txt

     time_namelookup:  %{time_namelookup}s\n
        time_connect:  %{time_connect}s\n
     time_appconnect:  %{time_appconnect}s\n
    time_pretransfer:  %{time_pretransfer}s\n
       time_redirect:  %{time_redirect}s\n
  time_starttransfer:  %{time_starttransfer}s\n
                     ----------\n
          time_total:  %{time_total}s\n