HTTP Client

Complete guide for integrating with NCN Network using HTTP REST API.

---

Overview

The HTTP API provides:

• Simple REST interface

• JSON request/response format

• Easy integration with any language

• Web browser compatibility

---

Base URL

Environment	URL
Local	http://localhost:8080
Testnet	https://api.testnet.ncn-network.io
Mainnet	https://api.ncn-network.io

---

Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 3600
}

Submit Inference

POST /api/v1/inference
Content-Type: application/json

{
  "model_uuid": "bark_semantic",
  "input_data": "{\"text\": \"Hello, world!\"}"
}

Response:

{
  "request_id": "req-abc123",
  "status": "queued",
  "payment_required": false
}

Get Task Status

GET /api/v1/inference/{request_id}

Response:

{
  "request_id": "req-abc123",
  "status": "completed",
  "output_data": "{\"tokens\": [1, 2, 3]}",
  "error_message": null
}

List Models

GET /api/v1/models

Response:

{
  "models": [
    {
      "model_uuid": "bark_semantic",
      "name": "Bark Semantic Model",
      "category": "audio",
      "description": "Text to semantic tokens"
    }
  ]
}

---

Client Examples

cURL

# Submit inference
curl -X POST http://localhost:8080/api/v1/inference \
  -H "Content-Type: application/json" \
  -d '{
    "model_uuid": "bark_semantic",
    "input_data": "{\"text\": \"Hello, world!\"}"
  }'

# Get status
curl http://localhost:8080/api/v1/inference/req-abc123

# Health check
curl http://localhost:8080/health

Python (requests)

import requests
import json
import time

class NCNHttpClient:
    def __init__(self, base_url='http://localhost:8080'):
        self.base_url = base_url
        self.session = requests.Session()
    
    def submit_inference(self, model_uuid, input_data):
        """Submit an inference request."""
        response = self.session.post(
            f"{self.base_url}/api/v1/inference",
            json={
                "model_uuid": model_uuid,
                "input_data": json.dumps(input_data) if isinstance(input_data, dict) else input_data
            }
        )
        response.raise_for_status()
        return response.json()
    
    def get_status(self, request_id):
        """Get task status."""
        response = self.session.get(
            f"{self.base_url}/api/v1/inference/{request_id}"
        )
        response.raise_for_status()
        return response.json()
    
    def inference(self, model_uuid, input_data, timeout=60, poll_interval=1):
        """Submit inference and wait for result."""
        # Submit
        result = self.submit_inference(model_uuid, input_data)
        request_id = result['request_id']
        
        # Poll for result
        start_time = time.time()
        while time.time() - start_time < timeout:
            status = self.get_status(request_id)
            
            if status['status'] == 'completed':
                return json.loads(status['output_data'])
            elif status['status'] == 'failed':
                raise Exception(status.get('error_message', 'Unknown error'))
            
            time.sleep(poll_interval)
        
        raise TimeoutError(f"Request {request_id} timed out")
    
    def health_check(self):
        """Check if gateway is healthy."""
        response = self.session.get(f"{self.base_url}/health")
        response.raise_for_status()
        return response.json()

# Usage
client = NCNHttpClient()
result = client.inference(
    model_uuid="bark_semantic",
    input_data={"text": "Hello, world!"}
)
print(result)

JavaScript (fetch)

class NCNHttpClient {
  constructor(baseUrl = 'http://localhost:8080') {
    this.baseUrl = baseUrl;
  }

  async submitInference(modelUuid, inputData) {
    const response = await fetch(`${this.baseUrl}/api/v1/inference`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model_uuid: modelUuid,
        input_data: typeof inputData === 'object' 
          ? JSON.stringify(inputData) 
          : inputData
      })
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }
    
    return response.json();
  }

  async getStatus(requestId) {
    const response = await fetch(`${this.baseUrl}/api/v1/inference/${requestId}`);
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
    }
    
    return response.json();
  }

  async inference(modelUuid, inputData, timeout = 60000, pollInterval = 1000) {
    // Submit
    const result = await this.submitInference(modelUuid, inputData);
    const requestId = result.request_id;
    
    // Poll for result
    const startTime = Date.now();
    while (Date.now() - startTime < timeout) {
      const status = await this.getStatus(requestId);
      
      if (status.status === 'completed') {
        return JSON.parse(status.output_data);
      } else if (status.status === 'failed') {
        throw new Error(status.error_message || 'Unknown error');
      }
      
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
    
    throw new Error(`Request ${requestId} timed out`);
  }

  async healthCheck() {
    const response = await fetch(`${this.baseUrl}/health`);
    return response.json();
  }
}

// Usage
const client = new NCNHttpClient();
const result = await client.inference('bark_semantic', { text: 'Hello, world!' });
console.log(result);

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

type NCNClient struct {
    BaseURL string
    Client  *http.Client
}

type InferenceRequest struct {
    ModelUUID string `json:"model_uuid"`
    InputData string `json:"input_data"`
}

type InferenceStatus struct {
    RequestID    string `json:"request_id"`
    Status       string `json:"status"`
    OutputData   string `json:"output_data"`
    ErrorMessage string `json:"error_message"`
}

func NewNCNClient(baseURL string) *NCNClient {
    return &NCNClient{
        BaseURL: baseURL,
        Client:  &http.Client{Timeout: 30 * time.Second},
    }
}

func (c *NCNClient) SubmitInference(modelUUID string, inputData interface{}) (*InferenceStatus, error) {
    inputJSON, _ := json.Marshal(inputData)
    
    reqBody, _ := json.Marshal(InferenceRequest{
        ModelUUID: modelUUID,
        InputData: string(inputJSON),
    })
    
    resp, err := c.Client.Post(
        c.BaseURL+"/api/v1/inference",
        "application/json",
        bytes.NewBuffer(reqBody),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var status InferenceStatus
    json.NewDecoder(resp.Body).Decode(&status)
    return &status, nil
}

func (c *NCNClient) GetStatus(requestID string) (*InferenceStatus, error) {
    resp, err := c.Client.Get(c.BaseURL + "/api/v1/inference/" + requestID)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    var status InferenceStatus
    json.NewDecoder(resp.Body).Decode(&status)
    return &status, nil
}

func (c *NCNClient) Inference(modelUUID string, inputData interface{}, timeout time.Duration) (map[string]interface{}, error) {
    result, err := c.SubmitInference(modelUUID, inputData)
    if err != nil {
        return nil, err
    }
    
    deadline := time.Now().Add(timeout)
    for time.Now().Before(deadline) {
        status, err := c.GetStatus(result.RequestID)
        if err != nil {
            return nil, err
        }
        
        if status.Status == "completed" {
            var output map[string]interface{}
            json.Unmarshal([]byte(status.OutputData), &output)
            return output, nil
        } else if status.Status == "failed" {
            return nil, fmt.Errorf("task failed: %s", status.ErrorMessage)
        }
        
        time.Sleep(1 * time.Second)
    }
    
    return nil, fmt.Errorf("timeout")
}

func main() {
    client := NewNCNClient("http://localhost:8080")
    
    result, err := client.Inference("bark_semantic", map[string]string{
        "text": "Hello, world!",
    }, 60*time.Second)
    
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    fmt.Printf("Result: %v\n", result)
}

---

Error Handling

HTTP Status Codes

Code	Meaning	Action
200	Success	Process response
400	Bad Request	Check input format
404	Not Found	Check request_id
429	Rate Limited	Retry with backoff
500	Server Error	Retry or report
503	Unavailable	Retry later

Error Response Format

{
  "error": {
    "code": "INVALID_MODEL",
    "message": "Model 'unknown' not found",
    "details": {}
  }
}

Retry Logic

import time
from requests.exceptions import RequestException

def retry_request(func, max_retries=3, backoff=1.0):
    for attempt in range(max_retries):
        try:
            return func()
        except RequestException as e:
            if attempt < max_retries - 1:
                if hasattr(e.response, 'status_code'):
                    if e.response.status_code in [429, 503]:
                        time.sleep(backoff * (2 ** attempt))
                        continue
            raise

---

Authentication (Future)

When API keys are implemented:

Authorization: Bearer YOUR_API_KEY

client = NCNHttpClient()
client.session.headers['Authorization'] = 'Bearer YOUR_API_KEY'

---

Rate Limiting

Limits

Endpoint	Limit
POST /api/v1/inference	100/min
GET /api/v1/inference/*	1000/min
GET /health	No limit

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067260

Handle Rate Limits

def handle_rate_limit(response):
    if response.status_code == 429:
        reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
        wait_time = max(reset_time - time.time(), 1)
        time.sleep(wait_time)
        return True
    return False

---

Next Steps

• gRPC Client - Higher performance option

• Payment Integration - Handle payments

• Examples - More code examples