Skip to content

REST API Reference Matrix ​

All ShellGuard endpoints return standard { success: boolean, data?: any, error?: string } JSON response envelopes.


🧭 Endpoint Matrix ​

1. Authentication ​

MethodPathAuth RequiredDescription
POST/api/auth/registerNoneRegister new identity (keyHash, username)
POST/api/auth/tokenNoneExchange key hash for session Bearer token
GET/api/auth/validateBearer TokenValidate current session token
POST/api/auth/logoutBearer TokenInvalidate current session token
GET/api/auth/meBearer TokenGet current authenticated lobster identity

2. Vault Pearls & Import Batches ​

MethodPathRequired PermissionDescription
GET/api/vaultcanReadList all vault pearls for owner (supports ?tags=a,b intersection filter; returns imported_at and import_batch_id)
POST/api/vaultcanWriteCreate a new vault pearl (supports tags, uris Layer 2 metadata encryption, and password_history Layer 1 ShellCryption)
POST/api/vault/bulk-importcanWriteBatch insert pearls (up to 1000 items, atomic transaction with per-record validation, stamps import_batch_id (imp_<uuid>) and imported_at; returns HTTP 201 { inserted, import_batch_id, imported_at } or HTTP 207 Multi-Status with errors)
POST/api/vault/import-batches/:id/graduatecanEditAtomically graduate an import batch across pearls, notes, and SSH keys by clearing imported_at and import_batch_id to NULL ({ graduated_count })
DELETE/api/vault/import-batches/:idcanDeleteAtomically revert an import batch across pearls, notes, and SSH keys, cascading to linked vault_secure_attachments and logging IMPORT_BATCH_REVERTED ({ deleted_count, deleted_attachments })
PUT/api/vault/:idcanEditUpdate an existing pearl (supports tags, uris, and password_history; auto-graduates item by clearing imported_at and import_batch_id to NULL)
DELETE/api/vault/bulkcanDeleteBatch delete pearls by IDs ({ ids: string[] }, owner-scoped, cascades linked attachments)
DELETE/api/vault/:idcanDeleteDelete pearl (cascades linked attachments)

3. Secure Notes & SSH Keys ​

MethodPathRequired PermissionDescription
GET/api/notescanReadList all secure notes (supports ?tags=a,b intersection filter; returns imported_at and import_batch_id)
POST/api/notescanWriteCreate a secure note (rejects payloads containing secret field with 400 Validation Error)
PUT/api/notes/:idcanEditUpdate an existing secure note (rejects secret field; auto-graduates item by clearing imported_at and import_batch_id to NULL)
DELETE/api/notes/:idcanDeleteDelete secure note (cascades linked attachments)
GET/api/keyscanReadList all SSH keys (supports ?tags=a,b intersection filter; returns imported_at and import_batch_id)
POST/api/keyscanWriteCreate an SSH key (supports tags and attachments JSON array)
PUT/api/keys/:idcanEditUpdate an existing SSH key (supports attachments; auto-graduates item by clearing imported_at and import_batch_id to NULL)
DELETE/api/keys/:idcanDeleteDelete an SSH key (cascades linked attachments)

4. Attachments (Reference Model — Phase 19 BLOB contract & Phase 20 Ceiling) ​

MethodPathRequired PermissionDescription
GET/api/attachmentscanReadList attachment metadata only (filters out quarantined files is_quarantined = 0; payload BLOB never included)
GET/api/attachments/:id/filecanReadStream the ciphertext BLOB (application/octet-stream, 1MB chunks; fails if quarantined)
POST/api/attachmentscanWriteMultipart upload of the client-encrypted ShellCryption envelope (requires valid parent_id and parent_type, standalone yields 400; 500 MB/file ceiling, 1000 MB grotto quota per owner — 413 on breach)
PUT/api/attachments/:idcanEditMetadata-only update (file replacement re-uploads)
DELETE/api/attachments/:idcanDeleteDelete an attachment record (frees grotto quota; transactionally purges ID from parent item's JSON array across pearls, notes, and SSH keys)
GET/api/attachments/quotacanReadPre-flight capacity check returning { used_bytes, quota_bytes, remaining_bytes } based on GROTTO_QUOTA_MB
POST/api/attachments/quarantine/sweepcanWriteRuntime orphan sweeper isolating unparented attachments on-demand. Returns count of quarantined orphan attachments.

5. Health & Skill Blueprint ​

MethodPathAuth RequiredDescription
GET/api/healthNoneSystem status, database health, version
GET/skill.mdNoneCanonical AI agent integration skill file

Sovereign Zero-Knowledge Secrets Vault. Released under AGPL-3.0. • Privacy Policy