API Reference

ChainLaunch Pro provides a comprehensive REST API for programmatic access to all platform features. This reference documents the main API endpoints and their usage.

Base URL

http://localhost:8080/api/v1

Authentication

All API requests must include authentication. Supported methods:

Bearer Token (API Key)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8080/api/v1/networks

Basic Auth

curl -u username:password \
  http://localhost:8080/api/v1/networks

Session Cookie

curl -b "session=YOUR_SESSION_ID" \
  http://localhost:8080/api/v1/networks

Common Response Format

Success Response

{
  "success": true,
  "data": {
    "id": "resource-123",
    "name": "example",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Network name is required",
    "details": {
      "field": "name",
      "reason": "missing"
    }
  }
}

Paginated Response

{
  "success": true,
  "data": [
    { "id": "1", "name": "network-1" },
    { "id": "2", "name": "network-2" }
  ],
  "pagination": {
    "total": 100,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Networks

List Networks

GET /networks

Query Parameters:

• limit (int) - Items per page (default: 10)
• offset (int) - Pagination offset (default: 0)
• type (string) - Filter by type: fabric or besu
• status (string) - Filter by status: running, stopped, error
• search (string) - Search by name

Example:

curl -X GET "http://localhost:8080/api/v1/networks?type=fabric&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": [
    {
      "id": "network-123",
      "name": "prod-network",
      "type": "fabric",
      "status": "running",
      "node_count": 4,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get Network Details

GET /networks/{networkId}

Example:

curl -X GET http://localhost:8080/api/v1/networks/network-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": "network-123",
    "name": "prod-network",
    "type": "fabric",
    "status": "running",
    "description": "Production network",
    "node_count": 4,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}

Create Network

POST /networks

Request Body:

{
  "name": "new-network",
  "type": "fabric",
  "description": "New Fabric network"
}

Example:

curl -X POST http://localhost:8080/api/v1/networks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "new-network",
    "type": "fabric",
    "description": "My network"
  }'

Start Network

POST /networks/{networkId}/start

Example:

curl -X POST http://localhost:8080/api/v1/networks/network-123/start \
  -H "Authorization: Bearer YOUR_API_KEY"

Stop Network

POST /networks/{networkId}/stop

Delete Network

DELETE /networks/{networkId}

Nodes

List Nodes

GET /nodes

Query Parameters:

• network_id (string) - Filter by network
• type (string) - Filter by type: peer, orderer, validator, bootnode
• status (string) - Filter by status: running, stopped, error

Example:

curl -X GET "http://localhost:8080/api/v1/nodes?network_id=network-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Node Details

GET /nodes/{nodeId}

Example:

curl -X GET http://localhost:8080/api/v1/nodes/node-123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "id": "node-123",
    "name": "peer-0",
    "type": "peer",
    "network_id": "network-123",
    "status": "running",
    "block_height": 1234,
    "peer_count": 3,
    "uptime_seconds": 86400,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Create Node

POST /networks/{networkId}/nodes

Request Body:

{
  "name": "peer-0",
  "type": "peer"
}

Start Node

POST /nodes/{nodeId}/start

Stop Node

POST /nodes/{nodeId}/stop

Restart Node

POST /nodes/{nodeId}/restart

Delete Node

DELETE /nodes/{nodeId}

Get Node Logs

GET /nodes/{nodeId}/logs

Query Parameters:

• tail (int) - Number of lines (default: 100)
• follow (bool) - Stream logs in real-time
• level (string) - Filter by level: debug, info, warn, error

Example:

curl -X GET "http://localhost:8080/api/v1/nodes/node-123/logs?tail=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Keys

List Keys

GET /keys

Query Parameters:

• type (string) - Filter by type: rsa, ecdsa, ed25519
• provider_id (string) - Filter by provider

Get Key Details

GET /keys/{keyId}

Create Key

POST /keys

Request Body:

{
  "name": "signing-key",
  "type": "ecdsa",
  "curve": "P-256",
  "provider_id": "provider-123"
}

Delete Key

DELETE /keys/{keyId}

Sign Data

POST /keys/{keyId}/sign

Request Body:

{
  "data": "aGVsbG8gd29ybGQ=",
  "algorithm": "SHA256"
}

Response:

{
  "success": true,
  "data": {
    "signature": "MEUCIQDx...",
    "algorithm": "SHA256"
  }
}

Audit Logs

List Audit Logs

GET /audit-logs

Query Parameters:

• user_id (string) - Filter by user
• action (string) - Filter by action type
• resource_type (string) - Filter by resource type
• start_date (string) - ISO 8601 start date
• end_date (string) - ISO 8601 end date
• status (string) - Filter by status: success, failed, denied

Example:

curl -X GET "http://localhost:8080/api/v1/audit-logs?action=NETWORK_CREATE&days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Audit Log Details

GET /audit-logs/{logId}

Users

List Users

GET /users

Get User Details

GET /users/{userId}

Create User

POST /users

Request Body:

{
  "email": "user@example.com",
  "name": "John Doe",
  "roles": ["operator"]
}

Update User

PUT /users/{userId}

Delete User

DELETE /users/{userId}

Get User Roles

GET /users/{userId}/roles

Assign Role to User

POST /users/{userId}/roles

Request Body:

{
  "role_id": "role-123"
}

API Keys

List API Keys

GET /api-keys

Create API Key

POST /api-keys

Request Body:

{
  "name": "ci-cd-key",
  "expires_at": "2025-12-31T23:59:59Z",
  "permissions": ["NODE_READ", "SYSTEM_MONITOR"]
}

Response:

{
  "success": true,
  "data": {
    "id": "key-123",
    "key": "clpro_abcd1234efgh5678ijkl9012mnop3456",
    "name": "ci-cd-key",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-12-31T23:59:59Z"
  }
}

Revoke API Key

DELETE /api-keys/{keyId}

Error Codes

Code	HTTP Status	Description
INVALID_REQUEST	400	Request validation failed
UNAUTHORIZED	401	Authentication required or failed
FORBIDDEN	403	Permission denied
NOT_FOUND	404	Resource not found
CONFLICT	409	Resource conflict (e.g., duplicate name)
UNPROCESSABLE_ENTITY	422	Semantic validation error
INTERNAL_ERROR	500	Internal server error
SERVICE_UNAVAILABLE	503	Service temporarily unavailable

Rate Limiting

The API implements rate limiting:

• Default: 1000 requests per minute per user
• Burst: Up to 50 concurrent requests
• Headers: Include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Example Response Header:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705322400

Pagination

List endpoints support cursor-based pagination:

Query Parameters:

• limit (int) - Items per page (default: 10, max: 100)
• offset (int) - Number of items to skip (default: 0)

Response:

{
  "data": [...],
  "pagination": {
    "total": 1000,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Filtering

Use query parameters to filter results:

# Filter by multiple conditions
GET /nodes?network_id=network-123&status=running&limit=20

Sorting

Most list endpoints support sorting:

# Sort by name ascending
GET /networks?sort=name

# Sort by created date descending
GET /networks?sort=-created_at

Webhooks

Receive real-time notifications of system events:

POST /webhooks

Request Body:

{
  "url": "https://example.com/webhook",
  "events": ["network.created", "node.started", "node.failed"],
  "active": true
}

SDK & Client Libraries

Go

import "github.com/chainlaunch/sdk-go"

client := sdk.NewClient("http://localhost:8080", "YOUR_API_KEY")
networks, _ := client.Networks.List(context.Background())

JavaScript/TypeScript

import { ChainLaunchClient } from '@chainlaunch/sdk-js';

const client = new ChainLaunchClient({
  baseURL: 'http://localhost:8080',
  apiKey: 'YOUR_API_KEY'
});

const networks = await client.networks.list();

Python

from chainlaunch_sdk import ChainLaunchClient

client = ChainLaunchClient(
    base_url='http://localhost:8080',
    api_key='YOUR_API_KEY'
)

networks = client.networks.list()

OpenAPI/Swagger

Complete OpenAPI 3.0 specification available at:

GET http://localhost:8080/api/v1/openapi.json
GET http://localhost:8080/api/v1/swagger

See Also

• RBAC & Permissions
• Audit Logging
• Getting Started