QShield API v2

Unified verification and trust scoring API for the QShield Trust Network

Authentication: All endpoints require an X-API-Key header.
Dev key for testing: qshield_dev_key_sprint1a

Trust Endpoints

GET /api/v2/trust/search

Search verified professionals and organizations.

Query Parameters

Param	Type	Description
`q`	string	Free-text search query
`industry`	string	Industry filter
`region`	string	City/region filter
`minKLevel`	integer	Minimum K-Level (0-4)
`limit`	integer	Results per page (default 10, max 100)
`offset`	integer	Pagination offset

curl -H "X-API-Key: qshield_dev_key_sprint1a" \
  "http://localhost:3847/api/v2/trust/search?q=cardiologist&region=san-francisco"

GET /api/v2/trust/verify/:qid

Verify a single identity by QID.

curl -H "X-API-Key: qshield_dev_key_sprint1a" \
  "http://localhost:3847/api/v2/trust/verify/qid:person:qshield:abc123"

POST /api/v2/trust/verify/batch

Batch-verify up to 50 QIDs at once.

curl -X POST -H "X-API-Key: qshield_dev_key_sprint1a" \
  -H "Content-Type: application/json" \
  -d '{"qids": ["qid:person:qshield:abc123"]}' \
  "http://localhost:3847/api/v2/trust/verify/batch"

Verify Endpoints

POST /api/v2/verify/identity

Look up and verify a user, organization, or agent by QID or email.

Request Body

Field	Type		Description
`entity_type`	string	required	"user", "organization", or "agent"
`identifier`	string	required	QID or email address

curl -X POST -H "X-API-Key: qshield_dev_key_sprint1a" \
  -H "Content-Type: application/json" \
  -d '{"entity_type": "user", "identifier": "qid:person:qshield:abc123"}' \
  "http://localhost:3847/api/v2/verify/identity"

Response

{
  "verified": true,
  "entity_type": "user",
  "trust_level": "B",
  "trust_score": 72,
  "details": {
    "name": "Jane Doe",
    "organization": null,
    "verification_method": "qid_lookup",
    "verified_at": "2025-01-15T10:30:00Z"
  },
  "request_id": "...",
  "processing_time_ms": 12
}

POST /api/v2/verify/voice

Upload an audio file for voice deepfake detection. Proxies to the QShield Voice Analysis service.

Request

Multipart form upload with an audio field containing the audio file (WAV, MP3, OGG, FLAC, M4A).

curl -X POST -H "X-API-Key: qshield_dev_key_sprint1a" \
  -F "audio=@sample.wav" \
  "http://localhost:3847/api/v2/verify/voice"

Response

{
  "voice_analysis": { ... },
  "request_id": "...",
  "processing_time_ms": 1500,
  "service": "qshield-voice-v1"
}

POST /api/v2/verify/message

Analyze text content for AI-generation indicators and optionally verify HMAC-SHA256 integrity.

Request Body

Field	Type		Description
`content`	string	required	Text content to analyze
`signature`	string	optional	HMAC-SHA256 hex signature for integrity check

curl -X POST -H "X-API-Key: qshield_dev_key_sprint1a" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, this is a test message."}' \
  "http://localhost:3847/api/v2/verify/message"

Response

{
  "origin": "human",
  "ai_probability": 0.1,
  "integrity": { "provided": false },
  "details": {
    "avg_sentence_length": 6,
    "vocabulary_diversity": 0.833,
    "punctuation_density": 0.032,
    "bigram_repetition_rate": 0,
    "word_count": 6,
    "sentence_count": 1
  },
  "request_id": "...",
  "processing_time_ms": 2
}

GET /api/v2/trust-score/:entity_id

Get the trust score, tier, contributing factors, and 30-day history for an entity.

curl -H "X-API-Key: qshield_dev_key_sprint1a" \
  "http://localhost:3847/api/v2/trust-score/qid:person:qshield:abc123"

Response

{
  "entity_id": "qid:person:qshield:abc123",
  "score": 72,
  "tier": "B",
  "factors": {
    "k_level": 2,
    "verified_emails": 150,
    "endorsements": 5,
    "anomaly_flags": 0,
    "active_days": 90
  },
  "history": [ ... ],
  "request_id": "..."
}

GET /api/v2/docs

This documentation page.

Alert Endpoints

POST /api/v2/alerts/webhooks

Request Body

Field	Type		Description
`url`	string	required	Webhook URL to receive alerts
`secret`	string	optional	Custom HMAC secret (auto-generated if omitted)

GET /api/v2/alerts/webhooks

List all registered webhooks for your organization.

POST /api/v2/alerts/webhooks/:id/test

Send a test ping to a registered webhook.

GET /api/v2/alerts

List recent alerts for your organization, with optional severity/category filters.

Query Parameters

Param	Type	Description
`page`	integer	Page number (default 1)
`limit`	integer	Results per page (default 20, max 100)
`severity`	string	Filter: critical, high, medium, low
`category`	string	Filter: prompt_injection, data_exfiltration, policy_violation, deepfake_detected, behavioral_anomaly

GET /api/v2/alerts/:id

Get a single alert with its webhook delivery history.

GET /api/v2/alerts/config

Get the current alert configuration (email, webhook, categories).

POST /api/v2/alerts/config

Update alert configuration (email recipients, severity threshold, categories).

Communication Endpoints

POST /api/v2/communication/verify-call

Verify trust scores for call/meeting participants in real time.

Request Body

Field	Type		Description
`participants`	array	required	Array of {name, email, phone?}
`platform`	string	required	zoom, teams, phone, or other
`meeting_id`	string	optional	Platform meeting ID

POST /api/v2/communication/verify-email

Analyze email sender trust, message provenance, and header authenticity.

Request Body

Field	Type		Description
`from`	string	required	Sender email address
`to`	string[]	required	Recipient email addresses
`subject`	string	required	Email subject line
`content`	string	required	Email body text
`headers`	object	optional	Raw email headers for SPF/DKIM analysis

POST /api/v2/communication/sign

Cryptographically sign a message for tamper-proof verification.

Request Body

Field	Type		Description
`content`	string	required	Message content to sign
`sender_id`	string	required	Signer identity (QID or user ID)

POST /api/v2/communication/verify-signature

Verify a previously signed message has not been tampered with.

Request Body

Field	Type		Description
`content`	string	required	Original message content
`signature`	string	required	Signature returned from /sign

OAuth 2.0 Endpoints

Note: The OAuth flow endpoints (/oauth/*) do not require an API key. Client management endpoints (/api/v2/oauth/clients) require an X-API-Key.

GET /oauth/authorize

Start the OAuth 2.0 authorization code flow. Redirects to the client's redirect_uri with an authorization code.

Query Parameters

Param	Type	Description
`response_type`	string	Must be "code"
`client_id`	string	Registered OAuth client ID
`redirect_uri`	string	Registered redirect URI
`scope`	string	Space-separated scopes (e.g. "verify:message trust:read")
`state`	string	CSRF protection state parameter

POST /oauth/token

Exchange an authorization code, refresh token, or client credentials for access tokens.

Supported grant_type values

Grant Type	Description
`authorization_code`	Exchange auth code for tokens
`refresh_token`	Refresh an expired access token
`client_credentials`	Server-to-server authentication

POST /oauth/revoke

Revoke an access token or refresh token (RFC 7009).

POST /api/v2/oauth/clients

Request Body

Field	Type		Description
`name`	string	required	Application name
`redirect_uris`	string[]	required	Allowed redirect URIs

GET /api/v2/oauth/clients

List all OAuth clients for your organization. Requires API key.

Error Format

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "X-API-Key header is required"
  },
  "request_id": "uuid-v4"
}

Rate Limits

Tier	Limit
Default (with API key)	100 req/min
Without API key	10 req/min

Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

QShield Trust Network — API v2 — Sprint 2