{"openapi":"3.0.3","info":{"title":"Flashpaper Agent Secret API","description":"Self-destructing secret sharing infrastructure for AI Agents (Cursor, Claude Desktop, OpenAI Custom GPTs, Zapier, n8n, LangChain, CrewAI). Uses server-side ephemeral encryption in RAM with zero disk persistence.","version":"1.0.0"},"servers":[{"url":"https://flashpaper.app","description":"Flashpaper Server"}],"paths":{"/api/agent/vault":{"post":{"operationId":"createAgentSecret","summary":"Encrypt and create a self-destructing burn link","description":"Encrypts sensitive payload in server RAM with AES-256-GCM. Returns a shareable URL containing the decryption key in the hash fragment (#). Cleartext is processed ephemerally in RAM and never written to disk.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["secretText"],"properties":{"secretText":{"type":"string","description":"The sensitive text, API key, connection string, or token to encrypt.","example":"sk_live_99a8b7c6d5e4f3a2b1"},"burnTrigger":{"type":"string","enum":["1_view","5_views","10_views","1_hour","12_hours","24_hours"],"default":"1_view","description":"Burn trigger condition or expiration TTL."},"antiScreenshot":{"type":"boolean","default":false,"description":"Enable anti-screenshot spotlight lens protection."},"viewTimerSeconds":{"type":"number","description":"Auto-destruct countdown timer in seconds after opening secret.","example":30},"agentName":{"type":"string","description":"Name of issuing AI agent (e.g. \"Cursor AI Assistant\").","example":"Cursor AI Assistant"},"agentPurpose":{"type":"string","description":"Purpose or context of secret creation.","example":"Database Provisioning"},"webhookUrl":{"type":"string","description":"Optional HTTPS webhook URL to receive POST notification when secret is claimed/revealed.","example":"https://agent.example.com/webhooks/pickup"}}}}}},"responses":{"200":{"description":"Secret created successfully in RAM memory","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"vaultId":{"type":"string","example":"d3b07384-d113-40a6-a730-b3b44e05e550"},"secretUrl":{"type":"string","example":"https://flashpaper.app/secret/d3b07384-d113-40a6-a730-b3b44e05e550#x7y8z9..."},"destroyUrl":{"type":"string","example":"https://flashpaper.app/api/vault/d3b07384-d113-40a6-a730-b3b44e05e550?token=..."},"destroyToken":{"type":"string"},"key":{"type":"string","example":"x7y8z9a1b2c3..."},"expiresAt":{"type":"string","example":"2026-07-27T10:00:00Z"},"maxViews":{"type":"integer","example":1},"encryptionMode":{"type":"string","example":"server-side-ephemeral"}}}}}}}}},"/api/agent/vault/{id}/claim":{"post":{"operationId":"claimAgentSecret","summary":"Claim and decrypt a secret deposited by another agent (Agent-to-Agent Handoff)","description":"Decrypts the secret in RAM using the provided key, returns plaintext exactly once, and burns the record. A 404 response indicates the secret was already consumed or expired — treat as a possible interception signal. Agents must use POST /api/agent/vault/:id/claim — never fetch the /secret/<id> HTML page directly.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The secret vault UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"type":"string","description":"The base64url decryption key","example":"x7y8z9a1b2c3d4e5f6g7h8i9j0"}}}}}},"responses":{"200":{"description":"Secret claimed successfully (plaintext returned once)","content":{"application/json":{"schema":{"type":"object","properties":{"secretText":{"type":"string","example":"db_password_123"},"agentName":{"type":"string","example":"Provisioner Agent A"},"agentPurpose":{"type":"string","example":"DB Credential Deposit"},"remainingViews":{"type":"integer","example":0},"burned":{"type":"boolean","example":true},"encryptionMode":{"type":"string","example":"server-side-ephemeral"}}}}}},"403":{"description":"Forbidden: Invalid decryption key. (View count is NOT incremented and record is NOT burned)"},"404":{"description":"Secret not found, expired, or already burned (Possible interception signal)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Secret not found, expired, or already burned."},"burned":{"type":"boolean","example":true}}}}}}}}},"/api/vault/{id}/status":{"get":{"operationId":"checkSecretStatus","summary":"Inspect status of a secret vault without burning it","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The secret vault UUID"}],"responses":{"200":{"description":"Vault status details"}}}},"/api/vault/{id}":{"delete":{"operationId":"burnSecretImmediately","summary":"Purge secret vault immediately using destroyToken","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Secret wiped from RAM memory"}}}}}}