API Overview

The Qpher API gives you programmatic access to post-quantum cryptographic operations — key encapsulation (KEM), key wrapping, digital signatures, hash-based signatures, key management, and tenant administration — through a single, consistent REST interface.

Base URL

All API requests are made to:

https://api.qpher.ai

Every endpoint is prefixed with /api/v1/. For example, the KEM encrypt endpoint is:

POST https://api.qpher.ai/api/v1/kem/encrypt

Authentication

Authenticate every request by including your API key in the X-API-Key header.

Authenticated request

curl -X GET https://api.qpher.ai/api/v1/kms/keys/active?algorithm=Kyber768 \
  -H "X-API-Key: qph_your_key_here" \
  -H "Content-Type: application/json"

🔒Keep your API key secret

Your API key is shown only once at creation time. Store it in a secrets manager or environment variable — never commit it to source control.

Content Type

All request and response bodies use JSON. Set the Content-Type header on every request:

Content-Type: application/json

Response Format

Success responses

Every successful response follows this structure:

{
  "data": {
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Field	Type	Description
data	object	The endpoint-specific result payload.
request_id	string (UUID)	Unique identifier for this request. Use it when contacting support.
timestamp	string (ISO 8601)	UTC timestamp of when the response was generated.

Error responses

Errors return an error object instead of data:

{
  "error": {
    "error_code": "ERR_AUTH_001",
    "message": "Missing or invalid API key"
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Field	Type	Description
error.error_code	string	A stable, machine-readable code like ERR_KEM_001. See the Error Codes reference.
error.message	string	A human-readable description of what went wrong.
request_id	string (UUID)	Same request ID — always include it in bug reports.
timestamp	string (ISO 8601)	UTC timestamp of the error.

Rate Limiting

Rate limits are enforced per tenant using a sliding window. The default limit is 1,000 requests per minute, though this varies by plan tier.

When you exceed the limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:

RequestPOST/api/v1/kem/encrypt

X-API-Key: qph_your_key_here
Content-Type: application/json

{
  "plaintext": "SGVsbG8=",
  "key_version": 1
}

Response429

{
  "error": {
    "error_code": "ERR_RATE_LIMIT_001",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  },
  "request_id": "d4e5f6a7-b8c9-0123-4567-890abcdef012",
  "timestamp": "2026-01-15T10:30:05.000Z"
}

💡Handling rate limits

Implement exponential backoff in your client. Respect the Retry-After header value to avoid cascading failures.

Rate limits by plan

Plan	Requests per minute
Free	100
Starter	500
Growth	1,000
Pro	5,000
Enterprise	Custom

Request IDs

Every response includes a request_id (UUID). If you send an X-Request-ID header with your request, the API will use your value; otherwise it generates one automatically.

Request IDs are essential for debugging. Always log them on your side, and include them in any support ticket:

X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

HTTP Status Codes

Code	Meaning
200	Success
400	Bad request — invalid input or parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — policy denied the request
404	Not found — resource does not exist
409	Conflict — duplicate or concurrent operation
422	Unprocessable entity — valid JSON but invalid values
429	Too many requests — rate limit exceeded
500	Internal server error
502	Bad gateway — downstream service failure
503	Service unavailable — fail-closed safety mode
504	Gateway timeout

Supported Algorithms

Qpher supports the following PQC and hybrid algorithms:

Algorithm	Standard	API Operations	Plans
Kyber768 (ML-KEM-768)	FIPS 203	/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate, /kem/key/wrap, /kem/key/unwrap	All (Key Wrap: Starter+)
Dilithium3 (ML-DSA-65)	FIPS 204	/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hash	All
X-Wing (X25519 + ML-KEM-768)	IETF CFRG draft	/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate, /kem/key/wrap, /kem/key/unwrap	Starter+
Composite-ML-DSA (ECDSA P-256 + ML-DSA-65)	IETF LAMPS draft	/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hash	Starter+

ℹ️Hybrid PQC + classical algorithms (Starter+)

Hybrid algorithms combine a PQC algorithm with a classical algorithm for defense-in-depth. Add "algorithm": "X-Wing" or "algorithm": "Composite-ML-DSA" to your request body. Omitting the parameter defaults to PQC-only (Kyber768 or Dilithium3). See Security Architecture for details.

OpenAPI Specification

Download machine-readable OpenAPI 3.1 specs for use with code generators, API clients, or AI tools:

Spec	Operations	Download
Unified (all APIs)	18 operations	qpher-api.yaml
KEM API	6 operations	kem.yaml
Signature API	4 operations	signature.yaml
Key Management API	5 operations	kms.yaml
Tenant API	3 operations	tenant.yaml

💡AI-friendly specs

All specs include example values on every field, making them ideal for AI coding assistants and LLM-powered API clients. Point your tool at the unified spec for complete coverage.

Next Steps

• KEM API — Encrypt, decrypt, key wrap, and key unwrap with Kyber768 or X-Wing
• Signature API — Sign, verify, sign-hash, and verify-hash with Dilithium3 or Composite-ML-DSA
• Key Management API — Generate, rotate, and manage PQC keys
• Key Wrap & Unwrap Guide — Protect symmetric keys with PQC key wrapping
• Hash-Based Signatures Guide — Sign pre-computed hashes for large files and streaming
• Error Codes — Full error code reference