Direct Module API Reference
Call each supported Sherlock trust module directly from your server application. Keep your own orchestration layer, user experience, and database. The graph builder is completely optional.
API Configuration & Authentication
Every direct API request is authenticated using a Bearer token issued from your workspace account in API access:
- Key format: Keys follow the pattern
sk_sherlock_[a-zA-Z0-9_-]{43}. - Storage: Raw secret keys are displayed only once upon generation. Sherlock persists only a SHA-256 digest. Store your key in an environment variable (e.g.
SHERLOCK_API_KEY). - Expiration: Keys expire automatically after 90 days. You can revoke any key immediately from the API access dashboard.
- Scoping: Each API key is strictly scoped to the modules you select during creation. Calls to un-scoped modules return
403 Forbidden.
Request Protocol & Headers
All direct module requests use HTTP POST with JSON request bodies:
| Header | Value | Description |
|---|---|---|
Authorization | Bearer sk_sherlock_... | Your scoped Sherlock integration key. |
Content-Type | application/json | Required for all request payloads. |
Idempotency-Key | <UUID> (optional) | Recommended for mutation tasks to guarantee once-only execution. |
Module Endpoints Matrix
Direct module requests follow the uniform endpoint structure: POST /api/v1/modules/:module.
| Module | Endpoint | Direct Status | Operations | Primary Input / Output |
|---|---|---|---|---|
| Policy | /api/v1/modules/policy | Active | evaluate | In: authenticity, identity, action, budget Out: decision, explanation, advisory |
| Voiceprint | /api/v1/modules/voiceprint | Active | detect, verify, enrol, speaker_delete, credits | In: base64 PCM16 audio, consent Out: status, score, reference |
| Pulse | /api/v1/modules/pulse | Active | observe | In: samples array, latencies array Out: count, mean, meanLatencyMs |
| Passport | /api/v1/modules/passport | Active | identity | In: empty object {}Out: principalId, authenticatedBy |
| Frontdoor | /api/v1/modules/frontdoor | Active | propose | In: transcript string Out: intent, reply, toolRequest |
| Gate | /api/v1/modules/gate | Active | hash | In: flat key-value parameter dictionary Out: parametersHash (SHA-256) |
| Ledger | /api/v1/modules/ledger | Active | verify | In: epoch, entries array Out: valid, count, headHash |
| Relay | /api/v1/modules/relay | Graph Only | delegate | Delegates between published graphs with cryptographic context tokens. Direct module call returns 501. |
| Bridge | /api/v1/modules/bridge | Graph Only | sandbox_transfer | Sandbox bank connector requiring interactive signed-in confirmation. Direct module call returns 501. |
Operational Limits & Error Codes
- Rate limits: Each API key permits up to 60 requests per minute across module endpoints. Provider calls (Voiceprint, Frontdoor) also respect daily owner attempt limits.
- Payload limits: Request bodies are capped at 6 MiB to accommodate base64-encoded audio up to ~4.5 MB.
- Execution timeouts: Direct module calls timeout after 45 seconds.
- Caching: All module responses set
Cache-Control: no-store.
| Status | Reason | Meaning & Resolution |
|---|---|---|
400 | Invalid Request | Malformed JSON, schema validation failure, or missing required parameter. |
401 | Unauthorized | Missing, invalid, expired, or revoked API key in Authorization header. |
403 | Forbidden | API key does not have permission for the requested module or is restricted to a graph. |
404 | Not Found | Module name or requested resource does not exist. |
413 | Payload Too Large | Request body exceeds 6 MiB limit. Compress audio or chunk transcripts. |
429 | Too Many Requests | Per-minute key rate limit or daily owner biometric attempt cap reached. |
501 | Not Implemented | Direct standalone invocation unavailable (e.g. Relay or Bridge graph-only operations). |
503 | Service Unavailable | Database, operational kill switch, or upstream AI/biometric provider unavailable. |
Self-Hosted Database & Environment Setup
To run Sherlock backend APIs locally or in private infrastructure, apply the database migrations:
# Apply migrations to PostgreSQL / Neon npm run db:migrate # Environment variables needed for direct API execution: DATABASE_URL="postgres://..." # Pooled connection DATABASE_URL_UNPOOLED="postgres://..." # Migration connection BETTER_AUTH_SECRET="..." # Workspace session secret GEMINI_API_KEY="..." # For Frontdoor conversational AI DETECTIF_API_KEY="..." # For Voiceprint biometric processing
Next Step: Explore the complete, copy-pasteable SDK code and end-to-end recipes in Direct API Boilerplate & Code Examples ↗.