REST API Reference Matrix
All ShellGuard endpoints return standard { success: boolean, data?: any, error?: string } JSON response envelopes.
🧭 Endpoint Matrix
1. Authentication
| Method | Path | Auth Required | Description |
|---|---|---|---|
POST | /api/auth/register | None | Register new identity (keyHash, username) |
POST | /api/auth/token | None | Exchange key hash for session Bearer token |
GET | /api/auth/validate | Bearer Token | Validate current session token |
POST | /api/auth/logout | Bearer Token | Invalidate current session token |
GET | /api/auth/me | Bearer Token | Get current authenticated lobster identity |
2. Vault Pearls & Import Batches
| Method | Path | Required Permission | Description |
|---|---|---|---|
GET | /api/vault | canRead | List all vault pearls for owner (supports ?tags=a,b intersection filter; returns imported_at and import_batch_id) |
POST | /api/vault | canWrite | Create a new vault pearl (supports tags, uris Layer 2 metadata encryption, and password_history Layer 1 ShellCryption) |
POST | /api/vault/bulk-import | canWrite | Batch 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/graduate | canEdit | Atomically 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/:id | canDelete | Atomically 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/:id | canEdit | Update 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/bulk | canDelete | Batch delete pearls by IDs ({ ids: string[] }, owner-scoped, cascades linked attachments) |
DELETE | /api/vault/:id | canDelete | Delete pearl (cascades linked attachments) |
3. Secure Notes & SSH Keys
| Method | Path | Required Permission | Description |
|---|---|---|---|
GET | /api/notes | canRead | List all secure notes (supports ?tags=a,b intersection filter; returns imported_at and import_batch_id) |
POST | /api/notes | canWrite | Create a secure note (rejects payloads containing secret field with 400 Validation Error) |
PUT | /api/notes/:id | canEdit | Update an existing secure note (rejects secret field; auto-graduates item by clearing imported_at and import_batch_id to NULL) |
DELETE | /api/notes/:id | canDelete | Delete secure note (cascades linked attachments) |
GET | /api/keys | canRead | List all SSH keys (supports ?tags=a,b intersection filter; returns imported_at and import_batch_id) |
POST | /api/keys | canWrite | Create an SSH key (supports tags and attachments JSON array) |
PUT | /api/keys/:id | canEdit | Update an existing SSH key (supports attachments; auto-graduates item by clearing imported_at and import_batch_id to NULL) |
DELETE | /api/keys/:id | canDelete | Delete an SSH key (cascades linked attachments) |
4. Attachments (Reference Model — Phase 19 BLOB contract & Phase 20 Ceiling)
| Method | Path | Required Permission | Description |
|---|---|---|---|
GET | /api/attachments | canRead | List attachment metadata only (filters out quarantined files is_quarantined = 0; payload BLOB never included) |
GET | /api/attachments/:id/file | canRead | Stream the ciphertext BLOB (application/octet-stream, 1MB chunks; fails if quarantined) |
POST | /api/attachments | canWrite | Multipart 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/:id | canEdit | Metadata-only update (file replacement re-uploads) |
DELETE | /api/attachments/:id | canDelete | Delete an attachment record (frees grotto quota; transactionally purges ID from parent item's JSON array across pearls, notes, and SSH keys) |
GET | /api/attachments/quota | canRead | Pre-flight capacity check returning { used_bytes, quota_bytes, remaining_bytes } based on GROTTO_QUOTA_MB |
POST | /api/attachments/quarantine/sweep | canWrite | Runtime orphan sweeper isolating unparented attachments on-demand. Returns count of quarantined orphan attachments. |
5. Health & Skill Blueprint
| Method | Path | Auth Required | Description |
|---|---|---|---|
GET | /api/health | None | System status, database health, version |
GET | /skill.md | None | Canonical AI agent integration skill file |