Skip to main content

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"
}
FieldTypeDescription
dataobjectThe endpoint-specific result payload.
request_idstring (UUID)Unique identifier for this request. Use it when contacting support.
timestampstring (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"
}
FieldTypeDescription
error.error_codestringA stable, machine-readable code like ERR_KEM_001. See the Error Codes reference.
error.messagestringA human-readable description of what went wrong.
request_idstring (UUID)Same request ID — always include it in bug reports.
timestampstring (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="
}
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​

PlanRequests per minute
Free100
Starter500
Growth1,000
Pro5,000
EnterpriseCustom

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​

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

Supported Algorithms​

Qpher supports the following PQC and hybrid algorithms:

AlgorithmStandardAPI OperationsPlans
ML-KEM-768 (wire value Kyber768)FIPS 203/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate, /kem/key/wrap, /kem/key/unwrapAll (Key Wrap: Starter+)
ML-DSA-65 (wire value Dilithium3)FIPS 204/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashAll
X-Wing (X25519 + ML-KEM-768)IETF CFRG draft/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate, /kem/key/wrap, /kem/key/unwrapStarter+
Composite-ML-DSA (ECDSA P-256 + ML-DSA-65)IETF LAMPS draft/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashStarter+
ML-KEM-1024 (NIST Category 5)FIPS 203/kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulateEnterprise+ (CNSA 2.0)
ML-DSA-87 (NIST Category 5)FIPS 204/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashEnterprise+ (CNSA 2.0)
SLH-DSA-SHA2 (128s / 128f / 192s / 256s)FIPS 205/signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hashStarter+
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.

CNSA 2.0 algorithm alignment (Enterprise+)

ML-KEM-1024 and ML-DSA-87 are the NIST Category 5 (highest-strength) parameter sets — the algorithms named in the NSA CNSA 2.0 suite for key establishment and digital signatures. The Qpher SDKs expose a single compliance_profile="cnsa-2.0" selector that pins every operation to ML-KEM-1024 + ML-DSA-87 + AES-256-GCM (pure post-quantum — hybrid is off under this profile) and rejects any non-Category-5 override. At the API level this is signalled with the X-Compliance-Profile: cnsa-2.0 request header.

This is algorithm alignment with the CNSA 2.0 suite — it is not a compliance certification or accreditation. See your SDK's compliance_profile parameter on the SDKs overview.

SLH-DSA — hash-based signatures (FIPS 205, Starter+)

SLH-DSA (Stateless Hash-Based Digital Signature Algorithm) is the third NIST PQC signature standard. Unlike ML-DSA (lattice-based), its security rests on hash functions, giving cryptographic diversification — a break in lattice cryptanalysis does not affect it. Qpher implements the four SHA2 parameter sets:

ValueNIST LevelSignature sizeUse case
SLH-DSA-SHA2-128s1~7.8 KBGeneral hash-based signing (smallest)
SLH-DSA-SHA2-128f1~17 KBLatency-sensitive Level 1
SLH-DSA-SHA2-192s3~16 KBLong-term / archival documents
SLH-DSA-SHA2-256s5~30 KBTop-tier archival

Pass the value in "algorithm" on the signature endpoints. Signatures are larger and signing is slower (~0.3–2 s) than ML-DSA — choose it when you want hash-based diversification or long-term assurance. Qpher implements the FIPS 205 algorithms; this is not a FIPS validation or certification.

OpenAPI Specification​

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

SpecOperationsDownload
Unified (all APIs)18 operationsqpher-api.yaml
KEM API6 operationskem.yaml
Signature API4 operationssignature.yaml
Key Management API5 operationskms.yaml
Tenant API3 operationstenant.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​