API Reference

Complete reference for the Harpocrates API endpoints and SDK methods.

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer hpc_your_api_key_here

API keys follow the format hpc_followed by 32 alphanumeric characters.

POST /infer

Perform confidential AI inference on encrypted data.

Request Body

{
  "model": "llm-secure-7b",
  "input": "encrypted_base64_string",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 512,
    "top_p": 0.9
  },
  "return_attestation": true
}

Response

{
  "id": "inf_1234567890abcdef",
  "object": "inference",
  "created": 1704067200,
  "model": "llm-secure-7b",
  "output": "encrypted_base64_response",
  "attestation": {
    "proof": "zk_proof_data",
    "enclave_id": "sgx_enclave_measurement",
    "timestamp": 1704067200
  },
  "usage": {
    "input_tokens": 42,
    "output_tokens": 128,
    "cost_eth": "0.00025"
  }
}

Parameters

modelrequired

The model ID to use for inference. See the Models page for available options.

inputrequired

Base64-encoded encrypted prompt. Use the SDK's encrypt() method.

parametersoptional

Model-specific generation parameters like temperature and max_tokens.

return_attestationoptional

Whether to include ZK attestation in the response. Defaults to true.

POST /embedding

Generate encrypted embeddings for semantic search and retrieval.

Request Body

{
  "model": "embed-secure-base",
  "input": "encrypted_base64_string",
  "dimensions": 768
}

Response

{
  "id": "emb_abcdef1234567890",
  "object": "embedding",
  "created": 1704067200,
  "model": "embed-secure-base",
  "embedding": [0.023, -0.045, 0.891, ...],
  "usage": {
    "input_tokens": 15,
    "cost_eth": "0.00005"
  }
}

POST /verifyAttestation

Verify a zero-knowledge attestation from a previous inference request.

Request Body

{
  "attestation": {
    "proof": "zk_proof_data",
    "enclave_id": "sgx_enclave_measurement",
    "timestamp": 1704067200
  },
  "inference_id": "inf_1234567890abcdef"
}

Response

{
  "valid": true,
  "verified_at": 1704067300,
  "enclave_verified": true,
  "proof_verified": true,
  "on_chain_receipt": "0x1234...abcd"
}

Error Handling

The API uses standard HTTP status codes and returns structured error objects:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_model",
    "message": "The model 'invalid-model' does not exist",
    "param": "model"
  }
}

Common Error Codes

400Bad Request - Invalid parameters

401Unauthorized - Invalid API key

429Too Many Requests - Rate limit exceeded

500Internal Server Error - Something went wrong

503Service Unavailable - Enclave temporarily unavailable

Always implement retry logic with exponential backoff for 500 and 503 errors.