API Overview
Qpher API gives your organization's systems the engine behind Qpher Vault: encrypt, sign, verify and manage keys over REST.
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.
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"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 limit depends on your plan: the Developer plan has one band; Qpher Vault Organization has three bands that grow with the organization's seat count; Institution limits are set in the agreement. Key generation and rotation (/kms/keys/generate, /kms/keys/rotate) are limited separately to one request per minute per algorithm. The figures are published in the Acceptable Use Policy, Section 3, which is the authority when this page and the policy differ. Calls made from a Qpher Console session to PQC paths count against the organization's plan band; organizations on a plan that is no longer sold use the seat bands.
When you exceed the limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:
/api/v1/kem/encryptX-API-Key: qph_your_key_here
Content-Type: application/json{
"plaintext": "SGVsbG8="
}{
"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"
}Implement exponential backoff in your client. Respect the Retry-After header value to avoid cascading failures.
Rate limits by plan
| Plan | How the limit is set |
|---|---|
| Developer | One fixed band for every Developer tenant |
| Qpher Vault Organization | Three bands by the organization's seat count; SLH-DSA and Composite-PQC signing have their own, lower band |
| Institution | Set in the agreement |
The numbers for each band are in the Acceptable Use Policy, Section 3.
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 |
|---|---|---|---|
ML-KEM-768 (wire value Kyber768) | FIPS 203 | /kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate, /kem/key/wrap, /kem/key/unwrap | All (Key Wrap: paid plans; Key Unwrap: all plans) |
ML-DSA-65 (wire value Dilithium3) | 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 | Paid plans |
| Composite-ML-DSA (ECDSA P-256 + ML-DSA-65) | IETF LAMPS draft | /signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hash | Paid plans |
| ML-KEM-1024 (NIST Category 5) | FIPS 203 | /kem/encrypt, /kem/decrypt, /kem/encapsulate, /kem/decapsulate | All plans |
| ML-DSA-87 (NIST Category 5) | FIPS 204 | /signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hash | All plans |
| SLH-DSA-SHA2 (128s / 128f / 192s / 256s) | FIPS 205 | /signature/sign, /signature/verify, /signature/sign-hash, /signature/verify-hash | Paid plans |
The Plans column applies to the write side of each operation. Reading what you already protected — /kem/decrypt, /kem/decapsulate, /kem/key/unwrap, /signature/verify and /signature/verify-hash — works on every plan for every algorithm listed, including after a subscription ends, within the Developer plan's monthly limit and rate.
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.
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. That pinning is
applied by the SDK, on every request. The SDK also sends an
X-Compliance-Profile: cnsa-2.0 header to signal intent, but the API does not
consume it today — there is no server-side gate that rejects a non-Category-5
algorithm on the basis of the profile.
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 (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:
| Value | NIST Level | Signature size | Use case |
|---|---|---|---|
SLH-DSA-SHA2-128s | 1 | ~7.8 KB | General hash-based signing (smallest) |
SLH-DSA-SHA2-128f | 1 | ~17 KB | Latency-sensitive Level 1 |
SLH-DSA-SHA2-192s | 3 | ~16 KB | Long-term / archival documents |
SLH-DSA-SHA2-256s | 5 | ~30 KB | Top-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:
| 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 |
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 ML-KEM-768 or X-Wing
- Signature API — Sign, verify, sign-hash, and verify-hash with ML-DSA-65 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