Skip to content

Latest commit

 

History

History
216 lines (153 loc) · 3.65 KB

API.md

File metadata and controls

216 lines (153 loc) · 3.65 KB

API Documentation

The Node Gateway API provides endpoints for zero-knowledge proof operations, system monitoring, and public key distribution. All endpoints are prefixed with /v1.

Base URL

http://localhost:3000/v1

Authentication

Most endpoints require an API key for authentication and to bypass rate limiting. Include the API key in the X-API-Key header:

X-API-Key: your_api_key_here

Endpoints

Summary

curl

curl -X GET http://localhost:3000/v1/health
curl -X GET "http://localhost:3000/v1/metrics?count=5" -H "X-API-Key: dummy"
curl -X GET http://localhost:3000/v1/public-key
curl -X GET "http://localhost:3000/v1/proof/result?requestId=dummy"
curl -X POST http://localhost:3000/v1/proof/create -d "encryptedData=your_encrypted_value_here"

http

http :3000/v1/health
http http://localhost:3000/v1/metrics count==5 X-API-Key:dummy
http :3000/v1/public-key
http http://localhost:3000/v1/proof/result requestId==dummy
http POST :3000/v1/proof/create encryptedData=your_encrypted_value_here

Health Check

GET /health

Check the health status of the API and its dependencies.

Response:

{
  "status": "OK",
  "timestamp": "2025-10-15T12:00:00.000Z",
  "application": {
    "version": "0.0.0"
  }
}

Example:

curl http://localhost:3000/v1/health

System Metrics

GET /metrics

Retrieve system performance metrics and rate limiting statistics.

Query Parameters:

  • count (optional): Number of metrics to return (1-100, default: 30)

Response:

{
  "metrics": [
    {
      "requestId": "abc123",
      "duration": 150,
      "timestamp": 1697365200000
    }
  ],
  "limit": {
    "activeCount": 2,
    "pendingCount": 0,
    "size": 3
  }
}

Example:

curl "http://localhost:3000/v1/metrics?count=10"

Public Key

GET /public-key

Retrieve the AWS KMS public key used for signature verification.

Response:

{
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}

Example:

curl http://localhost:3000/v1/public-key

Create Proof

POST /proof/create

Submit encrypted data for zero-knowledge proof generation.

Request Body:

{
  "encryptedData": "base64_encoded_encrypted_data"
}

Response:

{
  "requestId": "abc123def456"
}

Example:

curl -X POST http://localhost:3000/v1/proof/create \
  -H "Content-Type: application/json" \
  -d '{"encryptedData": "your_encrypted_data_here"}'

Get Proof Result

GET /proof/result

Retrieve the result of a previously submitted proof request.

Query Parameters:

  • requestId (required): The request ID returned from the create proof endpoint

Response (Processing):

{
  "status": "processing"
}

Response (Completed):

{
  "status": "completed",
  "result": "proof_data_here"
}

Response (Error):

{
  "status": "error",
  "message": "result not found"
}

Example:

curl "http://localhost:3000/v1/proof/result?requestId=abc123def456"

Status Codes

  • 200 OK: Request successful
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing API key
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Rate Limiting

The API implements rate limiting to prevent abuse. Requests are limited to 1000 requests per 10-minute window by default. Authenticated requests with a valid API key have higher limits.

Error Response Format

{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}